Deep Clarification

Principle

Premature convergence is the root cause of underspecified features. When uncertainty is high, exhaustive exploration of the decision space produces better artifacts than bounded clarification rounds.

When to Use

Interview Protocol

1. Identify the decision tree

Before asking the first question, map the branches:

• What are the top-level decisions that need to be made?
• Which decisions depend on others? (resolve dependencies first)
• Which decisions can be answered by exploring the codebase instead of asking the user?

2. Walk each branch

For each decision point:

1. State the question clearly: one question at a time
2. Provide a recommended answer: based on codebase exploration, existing ADRs, or domain knowledge
3. Wait for the user's response before proceeding to the next question
4. Challenge vague answers: if the response is ambiguous, probe deeper ("What do you mean by 'flexible'? Can you give a concrete example?")
5. Cross-reference with code: if the user states how something works, verify against the codebase. If there is a contradiction, surface it immediately.

3. Codebase-first resolution

Before asking the user a question, check if the answer is already in the codebase:

Can the codebase answer this question?
  YES → State the finding: "I found that [X]. Is this still current?"
  NO  → Ask the user

This reduces unnecessary questions and grounds the conversation in reality.

4. Convergence criteria

The clarification session ends when ANY of the following are true:

• Every branch of the decision tree has been explored and the user confirms shared understanding
• The user explicitly asks to stop or move on ("that covers it", "let's move on")
• Three consecutive questions yield no new information (diminishing returns)
• The session exceeds 15 questions without convergence (suggest parking unresolved items and continuing later)

5. Document decisions inline

As decisions are made during the session, capture them immediately:

• If a term is resolved: update the glossary (via domain-glossary skill if available)
• If an architectural decision emerges: note it for later ADR creation (do not create during the session)
• If a requirement is clarified: note it for spec update

Present a summary at the end using the reasoning skill format:

## Clarification Summary

### Decisions Made
| # | Decision | Justification | Confidence |
|---|----------|---------------|------------|
| 1 | [what was decided] | [why] | [High/Medium/Low] |

### Assumptions
- [assumption made during the session]

### Open Items
- [anything that could not be resolved and needs follow-up]

### Suggested Next Steps
- [ADR needed for X]
- [Spec update needed for Y]

Challenging Techniques

Use these patterns to probe deeper:

Auto-Clarity Exception

Temporarily pause the clarification session for:

• Security warnings that need immediate attention
• Irreversible action confirmations
• When the user explicitly asks to stop or move on

Resume after the exception is handled.

Anti-patterns

• Do not probe trivial decisions (formatting, naming conventions already established)
• Do not ask questions that can be answered by reading the codebase
• Do not batch questions: one at a time, wait for response
• Do not skip the summary: decisions made during the session must be captured
• Do not create ADRs or update specs during the session: capture notes and create afterward
• Do not continue probing after the user signals convergence ("that covers it", "let's move on")