This document describes the /speckit.clarify command, a structured clarification workflow that resolves ambiguities and underspecified areas in feature specifications before technical planning begins. This command operates between the specification phase (see /speckit.specify Command) and the planning phase (see /speckit.plan Command). For general quality validation and acceptance criteria, see /speckit.checklist Command.
The /speckit.clarify command implements a sequential, coverage-based questioning system that identifies gaps, ambiguities, and underspecified areas in feature specifications. Unlike ad-hoc free-form refinement through natural conversation, this command follows a structured interview process that systematically covers all aspects of the specification.
The command was formerly named /quizme and was promoted to a first-class workflow command due to its effectiveness in reducing downstream rework during the planning and implementation phases.
Sources: README.md267 README.md461-489
The clarification step occupies a critical position in the Spec-Driven Development workflow, serving as a quality gate between requirements gathering and technical design.
Sources: README.md461-489
The clarification command should be executed at a specific point in the workflow to maximize its effectiveness:
| Phase | Command | Clarification Status |
|---|---|---|
| 1 | /speckit.constitution | Not applicable |
| 2 | /speckit.specify | Creates base specification |
| 3 | /speckit.clarify | Resolves ambiguities |
| 4 | Ad-hoc refinement (optional) | Handles remaining edge cases |
| 5 | /speckit.plan | Consumes clarified specification |
Purpose: Running clarification before planning prevents the AI agent from making assumptions about underspecified areas, which would require costly rework when those assumptions prove incorrect.
Sources: README.md461-469
Sources: README.md467-471
Unlike ad-hoc conversation, /speckit.clarify systematically covers specification areas:
| Aspect | Ad-hoc Refinement | /speckit.clarify |
|---|---|---|
| Structure | Unstructured conversation | Sequential interview process |
| Coverage | Developer-driven, may miss areas | Systematic coverage of all sections |
| Recording | Scattered in conversation | Consolidated in Clarifications section |
| Completeness | No built-in validation | Coverage matrix ensures thoroughness |
| Traceability | Difficult to track what was clarified | Clear section with all Q&A pairs |
Sources: README.md467-471
The command updates the specification document with a dedicated section that records all clarifications:
The Clarifications section serves as:
Sources: README.md467-471
Impact on Planning: The /speckit.plan command reads the clarified specification, including the Clarifications section, reducing the likelihood of incorrect assumptions about feature behavior, edge cases, or user expectations.
Sources: README.md461-489
The command takes no arguments and operates on the current feature specification in the active Git branch.
Sources: README.md469
After /speckit.specify completes:
Execute /speckit.clarify:
Validate completeness:
Optional free-form refinement:
Sources: README.md461-489
Clarification can be intentionally skipped in specific scenarios:
| Scenario | Rationale | Action |
|---|---|---|
| Spike/Prototype | Exploring technical feasibility, not building production feature | Explicitly state intention to skip |
| Well-understood domain | Team has deep domain knowledge, specification is comprehensive | Optional skip with documentation |
| Time-boxed experiment | Rapid iteration more valuable than specification completeness | State time-box constraint |
Important: If skipping clarification, explicitly communicate this to the agent to prevent it from blocking on missing information during planning.
Sources: README.md471-473
The /speckit.clarify command is implemented as a command template that generates agent-specific command files during project initialization.
Format Variations:
$ARGUMENTS placeholder{{args}} placeholder and description + prompt structureSources: Diagram 4
| File | Purpose |
|---|---|
specs/NNN-feature-name/spec.md | Current specification to analyze |
.specify/memory/constitution.md | Constitutional principles for validation |
.specify/templates/spec-template.md | Template structure reference |
| File | Changes |
|---|---|
specs/NNN-feature-name/spec.md | Adds/updates Clarifications section Updates affected requirements Resolves [NEEDS CLARIFICATION] markers |
Sources: README.md467-471 Diagram 2
Before executing /speckit.clarify:
specs/NNN-feature-name/spec.md)After successful clarification:
/speckit.plan commandSources: README.md461-489
When answering clarification questions, provide complete information rather than minimal responses. The agent will use these answers during planning and implementation.
Example:
Use clarification as an opportunity to document edge cases that might not be obvious from the initial specification.
Reference the constitutional principles when answering questions to ensure consistency with project architecture decisions.
When clarifying one requirement, check if it affects related requirements and clarify those as well.
After clarification, explicitly validate the Review & Acceptance Checklist to ensure all criteria are met.
Sources: README.md482-489
Sources: README.md461-469
The /speckit.clarify command is registered in agent context files during project initialization by the specify init command. The command appears in the agent's command palette alongside other workflow commands.
Registration Locations by Agent:
| Agent | Command Registration |
|---|---|
| Claude Code | .claude/commands/clarify.md |
| Gemini CLI | .gemini/commands/clarify.toml |
| GitHub Copilot | .github/agents/clarify.md |
| Cursor | .cursor/commands/clarify.md |
| Windsurf | .windsurf/workflows/clarify.md |
| Other agents | Agent-specific directories |
| Command | Relationship to /speckit.clarify |
|---|---|
| /speckit.specify | Predecessor - Creates the specification that clarify operates on |
| /speckit.plan | Successor - Consumes the clarified specification |
| /speckit.checklist | Parallel - Validates specification quality from a different angle |
| /speckit.analyze | Successor - Cross-artifact validation after planning |
Sources: README.md245-269
Refresh this wiki