02 Clarify

## User Input

```text
$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Outline

Interview Protocol (One Question at a Time)

This command is an interactive interview loop.

• You MUST ask exactly one clarification question per run, then stop and wait for the user's answer.
• On subsequent runs, if $ARGUMENTS is non-empty, treat it as the answer to the most recently asked open question and immediately write it into spec.md before generating the next question.
• There is no cap on the number of questions. Continue until:
  • No [NEEDS CLARIFICATION] markers remain, and
  • No Open Questions remain in the ## Interview section of spec.md.

Persist interview state in spec.md under ## Interview:

• ### Open Questions (ordered)
• ### Answer Log (Q → A pairs, timestamped)
• **NEXT QUESTION:** #N marker

Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.

Note: This clarification workflow is expected to run (and be completed) BEFORE invoking /sp:03-plan. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.

Execution steps:

1. Run .specify/scripts/bash/check-prerequisites.sh --json --paths-only from repo root once (combined --json --paths-only mode / -Json -PathsOnly). Parse minimal JSON payload fields:

   • FEATURE_DIR
   • FEATURE_SPEC
   • (Optionally capture IMPL_PLAN, TASKS for future chained flows.)
   • If JSON parsing fails, abort and instruct user to re-run /sp:01-specify or verify feature branch environment.
   • For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot").

2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).

   Functional Scope & Behavior:

   • Core user goals & success criteria
   • Explicit out-of-scope declarations
   • User roles / personas differentiation

   Domain & Data Model:

   • Entities, attributes, relationships
   • Identity & uniqueness rules
   • Lifecycle/state transitions
   • Data volume / scale assumptions

   Interaction & UX Flow:

   • Critical user journeys / sequences
   • Error/empty/loading states
   • Accessibility or localization notes

   Non-Functional Quality Attributes:

   • Performance (latency, throughput targets)
   • Scalability (horizontal/vertical, limits)
   • Reliability & availability (uptime, recovery expectations)
   • Observability (logging, metrics, tracing signals)
   • Security & privacy (authN/Z, data protection, threat assumptions)
   • Compliance / regulatory constraints (if any)

   Integration & External Dependencies:

   • External services/APIs and failure modes
   • Data import/export formats
   • Protocol/versioning assumptions

   Edge Cases & Failure Handling:

   • Negative scenarios
   • Rate limiting / throttling
   • Conflict resolution (e.g., concurrent edits)

   Constraints & Tradeoffs:

   • Technical constraints (language, storage, hosting)
   • Explicit tradeoffs or rejected alternatives

   Terminology & Consistency:

   • Canonical glossary terms
   • Avoided synonyms / deprecated terms

   Completion Signals:

   • Acceptance criteria testability
   • Measurable Definition of Done style indicators

   Misc / Placeholders:

   • TODO markers / unresolved decisions
   • Ambiguous adjectives ("robust", "intuitive") lacking quantification

   For each category with Partial or Missing status, add a candidate question opportunity unless:

   • Clarification would not materially change implementation or validation strategy
   • Information is better deferred to planning phase (note internally)

3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:

   • Maximum of 10 total questions across the whole session.
   • Each question must be answerable with EITHER:
     • A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
     • A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").
   • Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
   • Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
   • Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
   • Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
   • If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.

4. Sequential questioning loop (interactive):

   • Present EXACTLY ONE question at a time.

   • For multiple‑choice questions:

     • Analyze all options and determine the most suitable option based on:
       • Best practices for the project type
       • Common patterns in similar implementations
       • Risk reduction (security, performance, maintainability)
       • Alignment with any explicit project goals or constraints visible in the spec
     • Present your recommended option prominently at the top with clear reasoning (1-2 sentences explaining why this is the best choice).
     • Format as: **Recommended:** Option [X] - <reasoning>
     • Then render all options as a Markdown table:

     | Option | Description