# 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 |