Vague: Requirement Clarification

Transform vague requirements into precise, actionable specifications through hypothesis-driven questioning.

When to Use

• Ambiguous feature requests ("add a login feature")

• Incomplete bug reports ("the export is broken")

• Underspecified tasks ("make the app faster")

For strategy/planning blind spot analysis, use unknown. For content-vs-form reframing, use metamedium.

Core Principle: Hypotheses as Options

Use AskUserQuestion for clarification. Do not ask open-ended free-text questions when options can represent plausible hypotheses.

• Bad: What kind of login do you want?

• Good: OAuth / Email+Password / SSO / Magic link

Each option should be a testable interpretation of user intent.

Invocation

Parse input:

• REQUIREMENT: requirement text (required)

• --max-iterations N: max rounds (default: 3)

Initialization

• Create .claude/clarify-vague.local.md :

active: true iteration: 1 max_iterations: [MAX_ITERATIONS] original_requirement: "[REQUIREMENT]" started_at: "[ISO timestamp]"

Original Requirement

"[REQUIREMENT]"

Clarification Progress

(Decisions are appended as the loop progresses)

• Confirm activation:

Vague clarification loop activated!

Original Requirement: "[REQUIREMENT]" Max Iterations: [MAX_ITERATIONS]

To cancel: /cancel

Protocol

Phase 1: Diagnose Ambiguity

Capture unknowns across categories:

• Scope

• Behavior

• Data / Interface

• Constraints / Priority

• Success criteria

Phase 2: Iterative Clarification

Use AskUserQuestion to resolve ambiguities.

Rules:

• Ask exactly 4 questions per round

• Use exactly 4 options per question

• Last question's last option must be: Clarification complete - proceed with current understanding

• Batch all 4 questions in a single AskUserQuestion call

• Cap total rounds by --max-iterations

Phase 3: Completion Check

Stop when either condition is met:

• User selects clarification-complete option

• Max iterations reached

Phase 4: Before/After Summary

Output:

Requirement Clarification Summary

Before (Original)

"{original requirement verbatim}"

After (Clarified)

Goal: [precise description] Reason: [why this matters] Scope: [included and excluded] Constraints: [limitations and preferences] Success Criteria: [how completion is verified]

Decisions Made:

Then output:

<promise>CLARIFICATION COMPLETE</promise>

Only output the promise when clarification is genuinely complete.

Question Design Rules

• Hypothesis options over open questions

• Neutral framing (avoid leading choices)

• One ambiguity axis per question

• Preserve user intent (refine, do not redirect)

• Keep language concrete and implementation-relevant

Now begin by creating the state file, identifying four critical ambiguities, and asking the first AskUserQuestion batch.