Speckit Clarify

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").

1. 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)

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

• Maximum of 5 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 `
• Then render all options as a Markdown table:

| Option | Description | |--------|-------------| | A | | | B | | | C | (add D/E as needed up to 5) | | Short | Provide a different short answer ( - `

• Then output: Format: Short answer ( → A: .
• Then immediately apply the clarification to the most appropriate section(s):
• Functional ambiguity → Update or add a bullet in Functional Requirements.
• User interaction / actor distinction → Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.
• Data shape / entities → Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.
• Non-functional constraint → Add/modify measurable criteria in Success Criteria > Measurable Outcomes (convert vague adjective to metric or explicit target).
• Edge case / negative flow → Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).
• Terminology conflict → Normalize term across spec; retain original only if necessary by adding (formerly referred to as "X") once.
• If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.
• Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).
• Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
• Keep each inserted clarification minimal and testable (avoid narrative drift).

1. Validation (performed after EACH write plus final pass):

• Clarifications session contains exactly one bullet per accepted answer (no duplicates).
• Total asked (accepted) questions ≤ 5.
• Updated sections contain no lingering vague placeholders the new answer was meant to resolve.
• No contradictory earlier statement remains (scan for now-invalid alternative choices removed).
• Markdown structure valid; only allowed new headings: ## Clarifications, ### Session YYYY-MM-DD.
• Terminology consistency: same canonical term used across all updated sections.

1. Write the updated spec back to FEATURE_SPEC.

1. Report completion (after questioning loop ends or early termination):

• Number of questions asked & answered.
• Path to updated spec.
• Sections touched (list names).
• Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
• If any Outstanding or Deferred remain, recommend whether to proceed to /speckit-plan or run /speckit-clarify again later post-plan.
• Suggested next command.

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: merllinsbeard
• Source: merllinsbeard/merlin-skills
• License: MIT

Install and usage instructions live in the source repository linked above.