# Speckit Clarify

> Spec-Kit: Clarify

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

---

# Spec-Kit: Clarify

Detect and reduce ambiguity in the feature spec by asking up to **5 targeted questions** and encoding the answers back into `spec.md`. This is the quality gate **before** planning. Invoked as `/speckit-clarify`.

**Lifecycle position** — step 2 of the chain:
[[speckit-specify]] → `/speckit-clarify` → [[speckit-plan]] → [[speckit-tasks]] → [[speckit-analyze]] → implement.

Run this after [[speckit-specify]] and **before** [[speckit-plan]]. If the user explicitly skips clarification (e.g. an exploratory spike), you may proceed — but warn that downstream rework risk rises.

## When to use

- A spec exists (from [[speckit-specify]]) and may contain `[NEEDS CLARIFICATION]` markers or vague language.
- Before planning, to lock down decisions that affect architecture, data modeling, or acceptance tests.

## What it produces

The same `spec.md`, updated in place with:

- A `## Clarifications` section containing a `### Session YYYY-MM-DD` subheading.
- One bullet per accepted answer: `- Q: <question> → A: <answer>`.
- The corresponding spec sections (requirements, user stories, data model, success criteria, edge cases) updated to reflect each answer.

## Flow

1. **Locate the spec.** If no spec file exists, stop and tell the user to run [[speckit-specify]] first — do not create one here.
2. **Load the constitution if present** (`.specify/memory/constitution.md`).
3. **Scan for ambiguity** across this taxonomy, marking each category Clear / Partial / Missing:
   - Functional scope & behavior (goals, out-of-scope, roles)
   - Domain & data model (entities, identity, lifecycle, scale)
   - Interaction & UX flow (journeys, error/empty/loading states, a11y)
   - Non-functional attributes (performance, scalability, reliability, observability, security/privacy, compliance)
   - Integration & external dependencies (APIs, failure modes, formats)
   - Edge cases & failure handling (negative paths, throttling, conflicts)
   - Constraints & tradeoffs; terminology consistency; completion signals (testable acceptance criteria); leftover placeholders / vague adjectives ("robust", "intuitive").
4. **Build a prioritized question queue (max 5).** Include a question only if its answer materially impacts architecture, data modeling, task decomposition, test design, UX, operational readiness, or compliance. Rank by `Impact × Uncertainty`. Each question must be answerable by a **2-5 option multiple choice** OR a **≤5-word short answer**.
5. **Ask one question at a time** (sequential loop):
   - For multiple choice: state your **Recommended** option with 1-2 sentences of reasoning, then render all options as a Markdown table, then let the user reply with a letter, "yes"/"recommended", or their own short answer.
   - For short answer: state a **Suggested** answer with brief reasoning, constrain to ≤5 words.
   - Never reveal future queued questions in advance.
6. **Integrate each answer immediately** (incremental, atomic save after each):
   - Append the `- Q: … → A: …` bullet under `## Clarifications`.
   - Apply the answer to the most appropriate section: functional ambiguity → Functional Requirements; actor/role → User Stories; data shape → Key Entities/Data Model; non-functional → Success Criteria (convert vague adjective to a metric); edge case → Edge Cases; terminology → normalize the term spec-wide.
   - If an answer invalidates earlier text, **replace** it — leave no contradictory statement behind.
7. **Stop early** when all critical ambiguities are resolved, the user signals completion ("done", "stop", "proceed"), or you reach 5 asked questions.
8. **Re-validate the quality checklist** if `checklists/requirements.md` exists — toggle only the `[ ]`/`[x]` markers whose pass state actually changed.

## Quality criteria

- Exactly one `## Clarifications` bullet per accepted answer; no duplicates.
- Total asked questions ≤ 5 (re-asking the same question for disambiguation doesn't count as new).
- Updated sections contain no leftover vague placeholder the answer was meant to resolve.
- One canonical term used consistently across all touched sections.
- Only new headings introduced are `## Clarifications` and `### Session YYYY-MM-DD`.

## Don'ts

- Don't exceed 5 questions, and don't ask low-impact or purely stylistic ones.
- Don't ask speculative tech-stack questions unless their absence blocks functional clarity — those belong in [[speckit-plan]].
- Don't create a spec here; if it's missing, defer to [[speckit-specify]].
- Don't reorder unrelated sections or disturb the heading hierarchy.
- Don't leave contradictory text after an answer supersedes it.

## Done when

- Ambiguities identified and each accepted answer integrated into `spec.md`.
- Quality checklist re-validated (if present).
- Reported back: questions asked/answered, sections touched, a coverage summary (Resolved / Deferred / Clear / Outstanding), and whether to proceed to [[speckit-plan]] or re-run clarify later.

## Going deeper

Previous: [[speckit-specify]]. Next: [[speckit-plan]] translates the now-clarified spec into a technical plan. Full chain: [[speckit-specify]] · [[speckit-plan]] · [[speckit-tasks]] · [[speckit-analyze]].