# Spec Kit Clarify

> Resolve ambiguities in a feature spec through targeted Q&A. Run after spec-kit-specify when open questions remain. Updates spec.md incrementally.

- Skill: `aircury/spec-kit-clarify` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aircury/spec-kit-clarify`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aircury/spec-kit-clarify/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: aircury (https://skillmd.com/u/aircury)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aircury/spec-kit-clarify

---


Resolve ambiguities in a feature spec through focused, sequential questioning.

**Input**: Optionally specify a change name. If omitted, infer from context or ask.

**Steps**

1. **Select the change**

   Auto-select if only one directory exists under `specs/changes/`. Otherwise ask.

2. **Load `specs/changes/<name>/spec.md`**

   If it does not exist, prompt the user to use the `spec-kit-specify` skill first.

3. **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.

4. **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.

 5. **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.