speckit.clarify — Claude Code command: clarify spec
speckit.clarify — a command that scans a feature spec for underspecified areas and asks up to 5 targeted questions to fill gaps before planning begins.
no license ★ 117 updated 2026-10-29
.claude/commands/speckit.clarify.mdWhat speckit.clarify does
Building from an unclear spec means starting with guesses. speckit.clarify reads your current feature spec and audits it across nine dimensions: functional scope, data model, interaction flows, non-functional quality attributes, integrations, edge cases, constraints, terminology, and completion signals. It identifies which gaps matter for architecture, testing, or acceptance.
The command loads the spec file, runs .specify/scripts/bash/check-prerequisites.sh --json --paths-only to locate your spec directory, and performs a structured coverage scan. When it finds ambiguity, it asks one question at a time—either offering a recommended answer with reasoning or presenting 2–5 discrete options. You accept the recommendation or provide your own; the clarification is recorded in memory and the next question follows. The output is an enriched spec ready for /speckit.plan.
If your spec is already complete or you skip clarification explicitly (e.g., for an exploratory spike), the command warns that rework risk increases downstream. Maximum 10 questions per session; each question expects a single-word or short-phrase answer, or a multiple-choice selection.
What it helps with
- identify incomplete specifications before development starts
- resolve ambiguous requirements with targeted structured questions
- fill gaps in data models, user flows, and non-functional requirements
- reduce rework risk at the planning phase
- prepare a spec for handoff to
/speckit.plan
Example prompts for the agent
- Clarify the spec before planning: /speckit.clarify
- Check specification completeness: /speckit.clarify Should we differentiate user roles?
- Skip clarification for a spike: /speckit.clarify This is exploratory, skip clarification
How to install speckit.clarify
Manually: put the files in place
.claude/commands/speckit.clarify.mdCall it with /speckit.clarify. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/speckit.clarify.mdCall it with /prompts:speckit.clarify. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/speckit.clarify.prompt.mdManually: put the files in place
.gemini/commands/speckit.clarify.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about speckit.clarify
How do I install speckit.clarify in Claude Code?
Copy the file .claude/commands/speckit.clarify.md into the .claude/commands/ directory at the root of your project. The command will then be available as /speckit.clarify.
What does speckit.clarify do?
It scans your feature spec for ambiguities and missing decisions across functional scope, data model, user flows, non-functional attributes, integrations, edge cases, and constraints. Then it asks targeted follow-up questions to resolve critical gaps before the plan is written.
Should I run speckit.clarify before /speckit.plan?
Yes. Clarification is meant to happen before planning, so the plan is built on a complete spec. If you skip clarification (e.g., for a spike), the command will note that downstream rework risk increases.