speckit-clarify

Identify underspecified areas in feature specs and encode clarification answers back into the spec.

Updated Sep 12, 2026
One-click install
npx skills add https://github.com/AndyRace/heart-rate-graph --skill speckit-clarify-andyrace
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: speckit-clarify
Source: https://github.com/AndyRace/heart-rate-graph/tree/main/.github/skills/speckit-clarify
Command: npx skills add https://github.com/AndyRace/heart-rate-graph --skill speckit-clarify-andyrace

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Feature specifications often contain ambiguities, missing decisions, and vague requirements that cause rework during planning and implementation. This Skill systematically detects underspecified areas in a spec-kit feature spec and resolves them through targeted clarification questions before planning begins. ## Core Features & Use Cases - Structured Ambiguity Scan: Evaluates the spec against a taxonomy covering functional scope, data model, UX flows, non-functional requirements, integrations, edge cases, and terminology. - Interactive Questioning Loop: Asks up to 5 high-impact questions one at a time, each with a recommended answer and multiple-choice or short-answer format. - Incremental Spec Updates: Writes each accepted answer into a ## Clarifications section and updates the relevant spec sections, then re-validates the requirements checklist. - Use Case: After running /speckit-specify to draft a feature spec, run this Skill to resolve open questions about security posture, scale targets, or edge-case behavior before invoking /speckit-plan. ## Quick Start Ask the assistant to run the speckit-clarify skill to review the current feature spec and resolve its ambiguities.

Frequently Asked Questions about speckit-clarify

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I clarify ambiguities in a spec-kit feature specification?

Run the speckit-clarify skill after creating a spec with /speckit-specify. It scans the spec for underspecified areas, asks up to 5 targeted questions one at a time, and writes the accepted answers directly into the spec file.

When should I run clarification in the spec-kit workflow?

Run clarification after /speckit-specify and before /speckit-plan. Resolving ambiguities before planning reduces downstream rework risk, though you can skip it for exploratory spikes at the cost of higher rework risk.

How many clarification questions does the skill ask per session?

The skill asks a maximum of 5 questions per session, selected by impact and uncertainty. Each question is multiple-choice or a short answer of five words or fewer, and retries for the same question do not count toward the limit.

Does speckit-clarify work without a spec-kit project structure?

No, it requires a spec-kit project with a .specify directory and an existing feature spec. If the spec file is missing, it instructs you to run /speckit-specify first rather than creating a new spec.

What happens to the requirements checklist after clarification?

If FEATURE_DIR/checklists/requirements.md exists, the skill re-evaluates each checkbox item against the updated spec, toggling only markers whose pass/fail state changed, and reports newly passing items, regressions, and remaining gaps.