deep-clarification

# 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: ```text ## 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")