spec-kit-clarify（规格套件澄清）

Spec Kit Clarify

Resolve high-impact ambiguity in the active feature specification before planning.

Invocation Notice

• Inform the user when this skill is being invoked by name: spec-kit-clarify.

When to Use

• spec.md already exists but has high-impact uncertainty.
• You see unresolved placeholders (for example [NEEDS CLARIFICATION], TODOs, or conflicting statements).
• Ambiguity could materially change architecture, data model, testing, UX behavior, operations, or compliance expectations.

When Not to Use

• No feature spec exists yet (spec-kit-specify first).
• Work is design decomposition (spec-kit-plan) or task generation (spec-kit-tasks).
• You only need read-only consistency analysis (spec-kit-analyze).
• You are reconciling broader cross-artifact drift (spec-kit-reconcile).

Router Fit

• Primary route from spec-kit after spec-kit-specify and before spec-kit-plan when ambiguity is still blocking.

Key Rules

• Ask exactly one question at a time.
• Ask at most 5 accepted questions per run.
• Every question must materially influence architecture, data model, testing, UX, operations, or compliance.
• Integrate each accepted answer into spec.md immediately.

Workflow

digraph clarify_workflow {
    rankdir=TB;
    node [fontname="Helvetica", fontsize=10];
    edge [fontname="Helvetica", fontsize=9];

    start [label="Invoke spec-kit-clarify", shape=doublecircle];
    resolve_paths [label="Resolve FEATURE_SPEC path", shape=box];
    has_spec [label="spec.md exists?", shape=diamond];
    stop_specify [label="STOP: run spec-kit-specify first", shape=octagon, style=filled, fillcolor=red, fontcolor=white];

    scan_taxonomy [label="Scan with clarification taxonomy", shape=box];
    has_high_impact [label="High-impact ambiguity remains?", shape=diamond];
    report_none [label="Report no critical ambiguity", shape=box];

    build_queue [label="Build and rank up to 5 questions", shape=box];
    ask_loop [label="Ask one question at a time\n(recommend/suggest, disambiguate if needed)", shape=box];
    integrate [label="Integrate accepted answer into spec.md", shape=box];
    validate [label="Validate update and consistency", shape=box];
    continue_gate [label="Continue loop?", shape=diamond];
    final_report [label="Report touched sections, coverage, next step", shape=box];
    done [label="Clarify complete", shape=doublecircle];

    start -> resolve_paths;
    resolve_paths -> has_spec;
    has_spec -> stop_specify [label="no"];
    has_spec -> scan_taxonomy [label="yes"];
    scan_taxonomy -> has_high_impact;
    has_high_impact -> report_none [label="no"];
    report_none -> done;
    has_high_impact -> build_queue [label="yes"];
    build_queue -> ask_loop;
    ask_loop -> integrate;
    integrate -> validate;
    validate -> continue_gate;
    continue_gate -> ask_loop [label="yes"];
    continue_gate -> final_report [label="no"];
    final_report -> done;
}

1. Resolve active spec path:

- Run scripts/check-prerequisites.sh --paths-only --json. - Read FEATURE_SPEC from the JSON payload. - If FEATURE_SPEC is missing, stop and direct the user to spec-kit-specify.

1. Build an internal ambiguity coverage map from spec.md:

- Use assets/clarification-taxonomy.md as the required category checklist. - Score each category as Clear, Partial, or Missing. - Create candidate questions only for Partial or Missing categories where clarification changes implementation or validation outcomes.

1. Prioritize up to 5 candidate questions:

- Rank by Impact * Uncertainty. - Exclude already-answered items, stylistic preferences, and low-impact plan-level details. - Ensure each question is answerable by either: - multiple choice with 2-5 mutually exclusive options, or - short answer constrained to <=5 words.

1. Run the interactive one-question loop:

- Follow the workflow chart above for branching and stop conditions. - Ask exactly one question at a time. - For multiple-choice questions, provide a recommendation and an options table. - For short-answer questions, provide a suggested answer and enforce <=5 words. - Accept yes, recommended, or suggested as confirmation of the current recommendation. - Use disambiguation follow-ups when needed without consuming a new question slot.

1. Integrate each accepted answer immediately:

- Ensure ## Clarifications exists. - Ensure a session heading exists: ### Session YYYY-MM-DD. - Append: - Q: <question> → A: <final answer>. - Update the most relevant section(s) inline: - functional behavior, - user stories/actors, - data model, - non-functional metrics, - edge/error handling, - terminology normalization. - Replace superseded contradictory statements instead of duplicating. - Save FEATURE_SPEC after each accepted answer.

1. Validate after each write and on final pass:

- Exactly one clarification bullet per accepted answer. - Accepted questions count is <=5. - No contradiction remains for resolved decisions. - No unresolved vague placeholder remains for resolved items. - Only these new headings are introduced: ## Clarifications, ### Session YYYY-MM-DD. - Canonical terminology is consistent across modified sections.

1. Report completion:

- Questions asked and answered. - Updated FEATURE_SPEC path. - Sections touched. - Coverage summary by category with status: - Resolved - Deferred - Clear - Outstanding - Next-step recommendation: proceed to spec-kit-plan or run clarify again later.

Behavior Rules

• If no high-impact ambiguity exists, respond: No critical ambiguities detected worth formal clarification. and suggest proceeding.
• Never exceed 5 accepted questions (disambiguation retries do not count as new questions).
• Respect early termination signals: stop, done, proceed.
• Avoid speculative tech-stack questions unless their absence blocks functional correctness.
• If quota is reached with unresolved high-impact items, mark them as Deferred with rationale.

Output

• Updated spec.md with embedded clarification history
• Summary of asked/answered questions, touched sections, and unresolved/deferred areas

Common Mistakes

• Low-impact questions. Never ask about cosmetic or stylistic details. Every question must materially affect architecture, data model, testing, UX, operations, or compliance.
• Asking multiple questions at once. Ask one question at a time. Batching questions overwhelms the user and produces shallow answers.
• Not updating spec inline. Each accepted answer must be applied to the relevant spec sections immediately. Never defer updates to a later pass.
• Redundant clarifications. Check existing spec content and prior clarification sessions before asking. Do not re-ask what is already resolved.

References

• assets/clarification-taxonomy.md
• references/spec-kit-workflow.dot for overall context of how the clarification fits into the Spec Kit process.
• scripts/check-prerequisites.sh
• https://github.com/github/spec-kit/blob/9111699cd27879e3e6301651a03e502ecb6dd65d/templates/commands/clarify.md