3.6 KiB
Adaptive Verbosity Pattern
Purpose
Scale output detail to match task complexity. Simple tasks get minimal output; complex tasks get thorough analysis.
Applicability
Use this pattern when:
- Skill handles both simple and complex scenarios
- Output length/detail should vary based on input
- User experience suffers from one-size-fits-all output
Do NOT use when:
- Skill always produces fixed output (lookups, status checks)
- User explicitly controls verbosity via flags
- Output is inherently simple (single values, yes/no)
Core Principle
Before generating output, assess complexity using multiple signals. Use the HIGHEST complexity level indicated by any signal.
Complexity Assessment
| Signal Type | Minimal | Standard | Detailed |
|---|---|---|---|
| Entity count | 1-5 | 6-10 | 10+ |
| Conversation context | Clear what/why from recent messages | Partial context | No context provided |
| Risk indicators | None | Minor (warnings) | Major (secrets, destructive) |
| User request style | Terse ("do it", "commit") | Neutral | Explicit detail request |
Note: Entity count thresholds (1-5/6-10/10+) are defaults. Adjust based on domain - e.g., 1-3 may be appropriate for complex entities like database migrations.
Precedence rule: If ANY signal indicates higher complexity, use that level.
Example: 2 entities (Minimal) + secrets detected (Detailed risk) → Use Detailed level
Output Formats
Minimal (simple tasks)
Direct result with single confirmation. No explanatory sections.
Example - Git commit:
Committed: `fix: correct typo in README`
Example - File operation:
Created: src/utils/helper.ts
Standard (moderate tasks)
Brief summary with key details. Clear action items if needed.
Example - Git commit:
Staged 4 files:
- src/auth/login.ts (new)
- src/auth/logout.ts (new)
- src/auth/index.ts (updated exports)
- tests/auth.test.ts (new)
Proposed: `feat(auth): add login and logout functions`
Commit? (y/n)
Detailed (complex tasks)
Full analysis with reasoning visible. Structured sections. Recommendations.
Example - Git commit:
Analysis of 15 changed files:
By concern:
- Authentication (8 files): New OAuth integration
- Validation (4 files): Extracted to shared module
- Tests (3 files): Coverage for above
Recommendation: Split into 3 commits:
1. `refactor(validation): extract shared module` [4 files]
2. `feat(auth): implement OAuth integration` [8 files]
3. `test: add auth and validation coverage` [3 files]
Rationale: Validation refactor is independent, should land first.
Proceed with split? (y/n/single commit)
Warning-focused (risky tasks)
Warnings FIRST and prominent. Risk explanation before any action. Explicit confirmation required.
Example - Git commit with secrets:
WARNING: Potential secrets detected
Files flagged:
- config/api-keys.json (contains "api_key" field)
- .env.production (environment file)
These files should NOT be committed.
Options:
1. Remove from staging: `git reset HEAD config/api-keys.json .env.production`
2. Add to .gitignore and remove
3. Proceed anyway (NOT RECOMMENDED)
Choice? (1/2/3)
Anti-patterns
| Anti-pattern | Problem | Fix |
|---|---|---|
| One-size-fits-all | Same verbose output for 1 file and 50 files | Assess complexity first |
| Always verbose | Detailed output when context is obvious | Trust conversation context |
| Always terse | Missing details when complexity warrants | Check entity count and risk signals |
| Ignoring risk | Burying warnings in normal output | Risk signals override other assessments |