deep-clarification

name

deep-clarification

description

Ask hard clarifying questions, stress-test assumptions, and challenge a plan or design until ambiguity is resolved. Exhaustively walks each branch of a decision tree. Use when deep clarification is needed during spec creation, planning, triage, or any phase with significant uncertainty. Also use when the user says 'challenge this', 'stress-test this', 'probe this plan', or 'deep dive on requirements'. Do not use for simple yes/no confirmations, for architecture decisions (use ADRs after clarification), or when the user explicitly asks for brevity.

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

Caller	Trigger
devsquad.specify	Spec touches multiple bounded contexts, has high complexity rating, or user requests deep exploration
devsquad.plan	High-impact design decisions with 2+ viable options and no clear winner
devsquad.envision	Business context has competing objectives or unclear pain points
debugging-recovery	Bug report is incomplete or ambiguous; need to build a complete reproduction
Any agent	User explicitly says "challenge this", "stress-test this", or "deep dive on requirements"

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:

Technique	When to use	Example
Concrete scenario	Vague requirement	"Give me a specific example of when this would happen"
Edge case probe	Happy path only discussed	"What happens if [unusual input]? What about [concurrent access]?"
Contradiction surfacing	User states conflict with code/docs	"Your code does X, but you just said Y. Which is correct?"
Terminology sharpening	Overloaded or vague terms	"You said 'account'. Do you mean the billing entity or the login identity?"
Scale probe	No volume context	"How many of these do you expect? 10? 10,000? 10 million?"
Failure mode	Only success path discussed	"What should happen when this fails? Is partial failure acceptable?"
Boundary probe	Scope unclear	"Is [X] in scope or out of scope for this feature?"

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")