b4san/spec-clarification

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.