speckit-clarify

name	speckit-clarify
description	Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
argument-hint	Optional areas to clarify in the spec
compatibility	Requires spec-kit project structure with .specify/ directory
metadata	{"author":"github-spec-kit","source":"templates/commands/clarify.md"}
user-invocable	true
disable-model-invocation	false

User Input

$ARGUMENTS

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

Pre-Execution Checks

Check for extension hooks (before clarification):

• Check if .specify/extensions.yml exists in the project root.
• If it exists, read it and look for entries under the hooks.before_clarify key
• If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
• Filter out hooks where enabled is explicitly false. Treat hooks without an enabled field as enabled by default.
• For each remaining hook, do not attempt to interpret or evaluate hook condition expressions:
  • If the hook has no condition field, or it is null/empty, treat the hook as executable
  • If the hook defines a non-empty condition, skip the hook and leave condition evaluation to the HookExecutor implementation
• When constructing slash commands from hook command names, replace dots (.) with hyphens (-). For example, speckit.git.commit → /speckit-git-commit.
• For each executable hook, output the following based on its optional flag:
  • Optional hook (optional: true):

    ## Extension Hooks
    
    **Optional Pre-Hook**: {extension}
    Command: `/{command}`
    Description: {description}
    
    Prompt: {prompt}
    To execute: `/{command}`
    

  • Mandatory hook (optional: false):

    ## Extension Hooks
    
    **Automatic Pre-Hook**: {extension}
    Executing: `/{command}`
    EXECUTE_COMMAND: {command}
    
    Wait for the result of the hook command before proceeding to the Outline.
    

• If no hooks are registered or .specify/extensions.yml does not exist, skip silently

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/bash/check-prerequisites.sh --json --paths-only 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

Behavior rules:

• If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
• If spec file missing, instruct user to run /speckit.specify first (do not create a new spec here).
• Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions).
• Avoid speculative tech stack questions unless the absence blocks functional clarity.
• Respect user early termination signals ("stop", "done", "proceed").
• If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.
• If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.

Context for prioritization: $ARGUMENTS

Post-Execution Checks

Check for extension hooks (after clarification): Check if .specify/extensions.yml exists in the project root.

• If it exists, read it and look for entries under the hooks.after_clarify key
• If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
• Filter out hooks where enabled is explicitly false. Treat hooks without an enabled field as enabled by default.
• For each remaining hook, do not attempt to interpret or evaluate hook condition expressions:
  • If the hook has no condition field, or it is null/empty, treat the hook as executable
  • If the hook defines a non-empty condition, skip the hook and leave condition evaluation to the HookExecutor implementation
• When constructing slash commands from hook command names, replace dots (.) with hyphens (-). For example, speckit.git.commit → /speckit-git-commit.
• For each executable hook, output the following based on its optional flag:
  • Optional hook (optional: true):

    ## Extension Hooks
    
    **Optional Hook**: {extension}
    Command: `/{command}`
    Description: {description}
    
    Prompt: {prompt}
    To execute: `/{command}`
    

  • Mandatory hook (optional: false):

    ## Extension Hooks
    
    **Automatic Hook**: {extension}
    Executing: `/{command}`
    EXECUTE_COMMAND: {command}
    

• If no hooks are registered or .specify/extensions.yml does not exist, skip silently

Ship Pipeline Guard

If .specify/.spex-state exists and its status is running, this command is part of an autonomous /spex:ship pipeline. Read the ask level from the state file. You MUST:

• If ask is smart or never: Do NOT present clarification questions to the user. Select the recommended answer for each question yourself. Process all questions in a single pass and update the spec.
• Do NOT output a completion summary.
• Do NOT ask "Ready for the next phase" or similar.
• Do NOT use AskUserQuestion (unless ask is always).
• Return immediately so the pipeline can advance to the next stage.