| name | spec-kit-clarify |
| description | Resolve ambiguities in a feature spec through targeted Q&A. Run after spec-kit-specify when open questions remain. Updates spec.md incrementally. |
| license | MIT |
| compatibility | No external workflow CLI required. |
| metadata | {"author":"Aircury","version":"1.0"} |
Resolve ambiguities in a feature spec through focused, sequential questioning.
Input: Optionally specify a change name. If omitted, infer from context or ask.
Steps
-
Select the change
Auto-select if only one directory exists under specs/changes/. Otherwise ask.
-
Load specs/changes/<name>/spec.md
If it does not exist, prompt the user to use the spec-kit-specify skill first.
-
Scan for ambiguities
Examine the spec for issues across these categories (in priority order):
- Functional scope — unclear boundaries or behavior
- Data models — undefined entities, states, or transitions
- UX flows — missing user journeys or edge cases
- Non-functional — unspecified performance, security, or scale requirements
- Integrations — undefined external dependencies
- Terminology — ambiguous or inconsistent domain language
Generate up to 5 questions total. Skip categories with no ambiguity.
-
Ask one question at a time
Format each question as multiple-choice (2–5 options) or a short answer (≤5 words).
Only ask a question if the answer materially impacts architecture, data modelling, testing, UX, operations, or compliance.
After each answer, update spec.md before asking the next question.
-
Finalise
After all questions are resolved (or the 5-question limit is reached), update the spec to:
- Remove resolved
[NEEDS CLARIFICATION] markers.
- Flag any remaining unresolved items explicitly.
Output
After completing all questions:
- Confirm how many ambiguities were resolved.
- List any items deferred (still open).
- Next step: "Use the
spec-kit-plan skill to create the technical implementation plan."
Guardrails
- Never ask more than 5 questions.
- Always save atomically after each answer — never batch updates.
- If all open questions are already resolved, report that and suggest the
spec-kit-plan skill.
- Never introduce implementation details into the spec during clarification.
