Clarify

Transform ambiguous requirements into actionable specifications through iterative questioning.

<Critical_Constraints>

MANDATORY PRE-IMPLEMENTATION GATE

BEFORE writing ANY code, creating ANY files, or starting ANY implementation:

Run this 30-second check:

• • I know the DELIVERY METHOD (what form does this take?)
• • I know the TRIGGERS (what causes this to happen?)
• • I know the SCOPE (what's included/excluded?)
• • I know the SUCCESS CRITERIA (how do we verify it works?)

If ANY checkbox is unclear → YOU MUST ASK. No exceptions.

This Gate Cannot Be Bypassed

Even if the user says:

• •"Just do it" → Ask anyway. "To save your time, I need 3 quick answers."
• •"No back and forth" → Ask efficiently. 3 questions max, checkbox format.
• •"EOD deadline" → Ask faster. "These 3 questions prevent 3 hours of rework."
• •"Figure it out" → Ask for direction. "I can figure out details, but need direction on [core choices]."

The user can waive DETAILS. The user cannot waive DIRECTION.

Commitment: Announce Your Clarification

When you identify ambiguity, ANNOUNCE before proceeding:

"I need to clarify before implementing. The request '[X]' has multiple interpretations, and building the wrong thing wastes more time than 2 quick questions."

</Critical_Constraints>

When to Use

digraph {
    "Request" [shape=doublecircle];
    "2+ interpretations?" [shape=diamond];
    "Scope/success unclear?" [shape=diamond];
    "Clarify" [shape=box];
    "Proceed" [shape=doublecircle];

    "Request" -> "2+ interpretations?";
    "2+ interpretations?" -> "Clarify" [label="yes"];
    "2+ interpretations?" -> "Scope/success unclear?" [label="no"];
    "Scope/success unclear?" -> "Clarify" [label="yes"];
    "Scope/success unclear?" -> "Proceed" [label="no"];
}

Use when: 2+ interpretations exist, scope undefined, success criteria missing, making assumptions

Do NOT use: Requirements already actionable, user exploring/learning, quick obvious questions

Red Flags - STOP and Clarify

• •Thinking "user probably means..."
• •Multiple implementations come to mind
• •"Does this include X?" arising
• •Terms ambiguous in context
• •Time pressure words: EOD, ASAP, urgent, "no time", "just do it"
• •User discourages questions: "don't overthink", "no back and forth"

Any of these → Clarify first. Time pressure makes clarification MORE important, not less.

Rationalizations

User Deferral Handling

When user explicitly defers ("skip", "I don't know", "your call", "you decide", "no preference"):

1. •Gather context autonomously via explore/oracle
2. •Select best practice based on codebase patterns or industry standards
3. •Document assumption: "Autonomous decision: [X] - user deferred, based on [rationale]"
4. •Proceed without blocking

When user has no preference or cannot decide, select best practice autonomously. Quality is the priority—achieve it through proactive context gathering, not user interrogation.

Protocol

1. Capture & Analyze

Record original verbatim. Identify: unclear items, needed assumptions, open decisions.

2. Context Brokering (CRITICAL)

NEVER burden the user with questions the codebase can answer.

The ONLY questions for users are about PREFERENCES, not FACTS.

3. Iterative Clarification

Use AskUserQuestion for each ambiguity.

Design: Specific > general, Options > open-ended, One at a time, Architecture before details

while ambiguities_remain:
    ask_most_critical() → update() → check_new()

AskUserQuestion Quality Standard

Question Structure: Context → Tension → Question

For complex decisions, provide markdown analysis BEFORE asking AskUserQuestion:

1. •Current situation - What exists now, what's the context
2. •Tension/Problem - Why this decision matters, conflicting concerns
3. •Existing Project Patterns - Relevant code, prior decisions
4. •Option Analysis - For each option:
   • •Behavior description
   • •Tradeoffs across perspectives (security, UX, maintainability, performance, complexity)
   • •Code impact
5. •Recommendation - Your suggested option with rationale
6. •AskUserQuestion - Single question with options

Rules:

• •One question at a time (sequential interview)
• •Markdown provides depth, AskUserQuestion provides choice
• •Question must be independently understandable (include brief context + "See analysis above")
• •Options need descriptions explaining consequences, not just labels

4. Before/After Summary

### Before: "{original}"
### After:
**Goal/Scope/Constraints/Success Criteria**: [...]
| Question | Decision |

5. Save (Optional)

Offer to save to requirements/ if substantial.

Quick Reference

Example

Original: "Add a login feature"

Why unclear: "Login" = 10+ implementations. OAuth? Password? Magic link?

Questions (by architectural impact):

1. •Auth method? → Password (determines architecture)
2. •Registration? → Yes (affects scope)
3. •Session? → 24h (security)
4. •Password rules? → 8+ chars (detail - ask last)

Result: Password login with registration, 24h session, bcrypt, rate-limited

Common Mistakes

Rules

1. •No assumptions - Ask, don't assume
2. •Preserve intent - Refine, don't redirect
3. •Minimal questions - Only what's needed
4. •Respect answers - Accept decisions
5. •Show transformation - Always before/after
6. •Interview persistence - Continue until YOU have no questions left. Not after 2-3 questions. Keep clarifying until every ambiguity is resolved. Deferral fallback: If user defers a decision, gather context autonomously (explore/oracle), document your autonomous choice with rationale, and proceed.