speckit-clarify

---

name: speckit-clarify description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.

User Input

Copy$ARGUMENTS

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

Memory Integration

Before Starting

Search for similar clarifications from prior features:

Copy./scripts/memory-search "clarifications for {feature domain}"

After Completion

Save Q&A decisions:

Copy./scripts/memory-save --decisions "Clarified for {feature}: {key decisions}" --issues ""

Constitution Alignment

This skill enforces project principles:

• Testable Requirements: Every requirement must be unambiguous and testable
• User-Focused: Clarifications prioritize user value over technical details

Outline

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 /speckit.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 /speckit.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).

   Taxonomy Categories:

   • Functional Scope & Behavior
   • Domain & Data Model
   • Interaction & UX Flow
   • Non-Functional Quality Attributes
   • Integration & External Dependencies
   • Edge Cases & Failure Handling
   • Constraints & Tradeoffs
   • Terminology & Consistency
   • Completion Signals
   • Misc / Placeholders

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.

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
     • Present your recommended option prominently at the top with clear reasoning
     • Format as: **Recommended:** Option [X] - <reasoning>
     • Then render all options as a Markdown table
   • After the user answers:
     • If the user replies with "yes", "recommended", or "suggested", use your previously stated recommendation/suggestion as the answer.
     • Otherwise, validate the answer maps to one option or fits the <=5 word constraint.
   • Stop asking further questions when:
     • All critical ambiguities resolved early (remaining queued items become unnecessary), OR
     • User signals completion ("done", "good", "no more"), OR
     • You reach 5 asked questions.

5. Integration after EACH accepted answer (incremental update approach):

   • Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.
   • Ensure a ## Clarifications section exists
   • Append a bullet line immediately after acceptance: - Q: <question>: A: <final answer>.
   • Then immediately apply the clarification to the most appropriate section(s)

6. Validation (performed after EACH write plus final pass):

   • Clarifications session contains exactly one bullet per accepted answer (no duplicates).
   • Total asked (accepted) questions <= 5.
   • Updated sections contain no lingering vague placeholders the new answer was meant to resolve.

7. Write the updated spec back to FEATURE_SPEC.

8. Report completion (after questioning loop ends or early termination):

   • Number of questions asked & answered.
   • Path to updated spec.
   • Sections touched (list names).
   • Coverage summary table listing each taxonomy category with Status
   • Suggested next command.

Handoff

After completing this skill:

• Create plan: Run /speckit.plan to generate technical implementation plan

References

• spec.md - Feature specification
• .specify/memory/constitution.md - Project principles