/speckit-clarify

name: speckit-clarify
description: Structured clarification workflow for underspecified requirements. Use
  before planning to resolve ambiguities through coverage-based questioning. Records
  answers in spec clarifications section.
compatibility: Requires spec-kit project structure with .specify/ directory
metadata:
  author: github-spec-kit
  source: templates/commands/clarify.md

Speckit Clarify Skill

User Input

$ARGUMENTS

You **MUST** consider the user input before proceeding (if not empty).

Outline

Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.

Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/speckit.plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.

Execution steps:

1. Run `.specify/scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields:

• `FEATURE_DIR`
• `FEATURE_SPEC`
• (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.)
• If JSON parsing fails, abort and instruct user to re-run `/speckit.specify` or verify feature branch environment.
• For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").

2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).

Functional Scope & Behavior:

• Core user goals & success criteria
• Explicit out-of-scope declarations
• User roles / personas differentiation

Domain & Data Model:

• Entities, attributes, relationships
• Identity & uniqueness rules
• Lifecycle/state transitions
• Data volume / scale assumptions

Interaction & UX Flow:

• Critical user journeys / sequences
• Error/empty/loading states
• Accessibility or localization notes

Non-Functional Quality Attributes:

• Performance (latency, throughput targets)
• Scalability (horizontal/vertical, limits)
• Reliability & availability (uptime, recovery expectations)
• Observability (logging, metrics, tracing signals)
• Security & privacy (authN/Z, data protection, threat assumptions)
• Compliance / regulatory constraints (if any)

Integration & External Dependencies:

• External services/APIs and failure modes
• Data import/export formats
• Protocol/versioning assumptions

Edge Cases & Failure Handling:

• Negative scenarios
• Rate limiting / throttling
• Conflict resolution (e.g., concurrent edits)

Constraints & Tradeoffs:

• Technical constraints (language, storage, hosting)
• Explicit tradeoffs or rejected alternatives

Terminology & Consistency:

• Canonical glossary terms
• Avoided synonyms / deprecated terms

Completion Signals:

• Acceptance criteria testability
• Measurable Definition of Done style indicators

Misc / Placeholders:

• TODO markers / unresolved decisions
• Ambiguous adjectives ("robust", "intuitive") lacking quantification

For each category with Partial or Missing status, add a candidate question opportunity unless:

• Clarification would not materially change implementation or validation strategy
• Information is better deferred to planning phase (note internally)

3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:

• Maximum of 10 total questions across the whole session.
• Each question must be answerable with EITHER:
• A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
• A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").
• Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
• Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
• Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
• Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
• If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.

4. Sequential questioning loop (interactive):

• Present EXACTLY ONE question at a time.
• For multiple‑choice questions:
• **Analyze all options** and determine the **most suitable option** based on:
• Best practices for the project type
• Common patterns in similar implementations
• Risk reduction (security, performance, maintainability)
• Alignment with any explicit project goals or constraints visible in the spec
• Present your **recommended option prominently** at the top with clear reasoning (1-2 sentences explaining why this is the best choice).
• Format as: `**Recommended:** Option [X] - <reasoning>`
• Then render all options as a Markdown table:

| Option | Description | |--------|-------------| | A | <Option A description> | | B | <Option B description> | | C | <Option C description> (add D/E as needed up to 5) | | Short | Provide a different short answer (<=5 words) (Include only if free-form alternative is appropriate) |

• After the table, add: `You can reply with th