Clarify Feature Specification

You are performing an interactive clarification session to identify and resolve underspecified areas in a feature specification. This is a refinement step best run between /spec-kit:specify and /spec-kit:plan.

Upstream source: github/spec-kit

Prerequisites

• A feature specification must exist at specs/[###-feature-name]/spec.md

If no spec exists, instruct the user to run /spec-kit:specify first.

Workflow

Step 1: Identify the Feature

• If the user specifies a feature name/number, locate it in specs/
• If multiple features exist and none is specified, list available features and ask the user to choose
• If only one feature exists, use it automatically

Step 2: Load and Analyze the Specification

Read specs/[###-feature]/spec.md and perform a structured ambiguity scan across these categories. Mark each as Clear / Partial / Missing:

1. Functional Scope & Behavior: Core user goals, success criteria, explicit out-of-scope declarations, user roles
2. Domain & Data Model: Entities, attributes, relationships, identity rules, lifecycle/state transitions
3. Interaction & UX Flow: Critical user journeys, error/empty/loading states, accessibility notes
4. Non-Functional Quality Attributes: Performance (latency, throughput), scalability, reliability, security & privacy, compliance
5. Integration & External Dependencies: External services/APIs, data import/export formats, failure modes
6. Edge Cases & Failure Handling: Negative scenarios, rate limiting, conflict resolution
7. Constraints & Tradeoffs: Technical constraints, explicit rejected alternatives
8. Terminology & Consistency: Canonical glossary terms, avoided synonyms
9. Completion Signals: Acceptance criteria testability, Definition of Done indicators, Misc/Placeholders (TODO markers, vague adjectives)

Build an internal priority queue of candidate clarification questions. Apply these constraints:

• Maximum 5 total questions across the whole session
• Each question must be answerable with a short multiple-choice selection (2-5 distinct options) OR a one-word/short-phrase answer (≤5 words)
• Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, or compliance
• Prioritize by (Impact × Uncertainty): scope > security/privacy > UX behavior > technical constraints
• Exclude questions already answered or that are plan-level execution details

Step 3: Interactive Clarification (Sequential, One at a Time)

Present exactly ONE question at a time. Never reveal future questions in advance.

For multiple-choice questions:

1. Analyze all options and determine the most suitable one based on best practices, risk reduction, and project context
2. Present your recommendation prominently: **Recommended:** Option [X] — [reasoning in 1-2 sentences]
3. Render all options as a Markdown table:

Option	Description
A	[First option description]
B	[Second option description]
C	[Third option description]
Custom	Provide your own short answer (≤5 words)

4. Add: You can reply with the option letter (e.g., "A"), accept the recommendation by saying "yes" or "recommended", or provide your own short answer.

For short-answer questions:

1. Provide your suggested answer: **Suggested:** [your proposed answer] — [brief reasoning]
2. Add: Format: Short answer (≤5 words). You can accept by saying "yes" or "suggested", or provide your own answer.

After each answer:

• If user replies "yes", "recommended", or "suggested" — use your stated recommendation/suggestion
• Validate the answer maps to one option or fits the ≤5 word constraint
• Record the answer in working memory and integrate it immediately into the spec (write to disk after each integration)
• Stop asking if: all critical ambiguities resolved, user signals completion ("done", "good", "no more"), or 5 questions reached

Step 4: Integration After Each Answer

After each accepted answer, integrate it into the spec file:

1. Ensure a ## Clarifications section exists (create it if missing, after the main spec sections)
2. Under it, create/update a ### Session YYYY-MM-DD subheading for today
3. Append a bullet: - Q: [question] → A: [final answer]
4. Apply the clarification to the most appropriate section:
   • Functional ambiguity → Update/add to Functional Requirements
   • User interaction → Update User Stories or add Edge Cases
   • Data shape/entities → Update Key Entities section
   • Non-functional constraint → Add/modify measurable criteria in Success Criteria
   • Terminology → Normalize term across spec
5. If the clarification invalidates an earlier ambiguous statement, replace it (don't duplicate)
6. Save the spec file after each integration (incremental saves reduce risk of context loss)

Step 5: Output Summary

Clarification Session Complete: specs/[###-feature-name]/spec.md

  Questions Asked: [count]/5
  Clarifications Resolved: [count]
  Remaining [NEEDS CLARIFICATION] markers: [count]

  Sections Updated:
    - [Section]: [What was clarified]
    - [Section]: [What was clarified]

  Coverage Summary:
    Resolved:     [categories addressed]
    Deferred:     [categories deferred to planning phase]
    Clear:        [categories already sufficient]
    Outstanding:  [categories still partial/missing - low impact]

  Spec Status: [Ready for planning / Still has outstanding items]

Next step: Run /spec-kit:plan to create the implementation plan.

Behavior Rules

• If no meaningful ambiguities found, respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
• If spec file missing, instruct user to run /spec-kit:specify first.
• Never exceed 5 total asked questions.
• Avoid speculative tech stack questions unless the absence blocks functional clarity.
• Respect user early termination signals ("stop", "done", "proceed").
• The ## Clarifications section serves as an audit trail — never delete previous session entries.