Specification Clarification

Overview

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

Goal: Identify 5 actionable clarification questions that materially impact implementation.

Execution Steps

1. •

   Initialize Context:

   • •Load the current spec file (spec.md).
   • •Perform a structured ambiguity & coverage scan.
   • •Identify missing or partial information in: Functional Scope, Domain & Data Model, Interaction & UX Flow, Non-Functional Quality, Integration & Dependencies, Edge Cases, Constraints, Terminology, Completion Signals, Misc/Placeholders.
2. •

   Generate Prioritized Questions:

   • •Create a queue of candidate clarification questions (max 5).
   • •Constraints:
     • •Answerable with Multiple Choice (2-5 options) OR Short Answer (<=5 words).
     • •Materially impacts architecture, data modeling, task decomposition, test design, UX, or compliance.
     • •Exclude style preferences or plan-level details unless blocking.
     • •Favor impact * uncertainty heuristic.
3. •

   Sequential Questioning Loop (Interactive):

   • •Present ONE question at a time.
   • •Multiple Choice:
     • •Analyze options based on best practices/risk/alignment.
     • •Present Recommended Option with reasoning first.
     • •Show table of options (A, B, C...).
     • •Prompt user to reply with letter or "yes"/"recommended".
   • •Short Answer:
     • •Provide Suggested Answer based on context.
     • •Prompt user to reply "yes"/"suggested" or own answer.
   • •After Answer:
     • •Validate answer.
     • •Record in working memory.
     • •Stop if: All critical ambiguities resolved, User says stop, or 5 questions reached.
4. •

   Integration (Incremental Update):

   • •After EACH accepted answer:
     • •Ensure a ## Clarifications section exists (create if missing).
     • •Append a bullet: - Q: <question> → A: <final answer>.
     • •Apply the clarification to the appropriate section(s) in the spec:
       • •Functional → Functional Requirements.
       • •User Interaction → User Stories/Actors.
       • •Data → Data Model.
       • •Non-Functional → NFRs.
       • •Edge Case → Edge Cases/Error Handling.
       • •Terminology → Normalize terms.
     • •Save the spec file immediately.
5. •

   Validation:

   • •Ensure exactly one bullet per answer.
   • •Ensure no contradictory earlier statements remain.
   • •Ensure Markdown structure is valid.
6. •

   Report Completion:

   • •Summarize questions asked & answered.
   • •List sections touched.
   • •Show coverage summary table (Resolved/Deferred/Clear/Outstanding).
   • •Recommend next steps (e.g., Proceed to Planning).

Principles

• •If no ambiguities, state "No critical ambiguities detected".
• •Never exceed 5 questions.
• •Avoid speculative tech stack questions unless blocking functional clarity.
• •Respect explicit user stops.