speckit-analyze
User Input
$ARGUMENTS
You MUST consider the user input before proceeding (if not empty).
Pre-Execution Checks
Check for extension hooks (before analysis):
- Check if
.specify/extensions.yml exists in the project root.
- If it exists, read it and look for entries under the
hooks.before_analyze key
- If the YAML cannot be parsed or is invalid, do not skip silently: tell the user that
.specify/extensions.yml could not be read (include the parser error) and that no hooks were checked, including any mandatory (optional: false) hooks registered there, then 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
- 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 Goal.
After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal {command} id shown above, e.g. a skills-mode agent runs it as /skill:speckit-... or $speckit-...). Emitting the block alone does not run the hook.
- If no hooks are registered or
.specify/extensions.yml does not exist, skip silently
Goal
Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (spec.md, plan.md, tasks.md) before implementation. This command MUST run only after speckit-tasks has successfully produced a complete tasks.md.
Operating Constraints
STRICTLY READ-ONLY: Do not modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
Constitution Authority: The project constitution (/memory/constitution.md) is non-negotiable within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside speckit-analyze.
Execution Steps
1. Initialize Analysis Context
Run .specify/scripts/bash/check-prerequisites.sh --json --require-spec --require-tasks --include-tasks once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
- SPEC = FEATURE_DIR/spec.md
- PLAN = FEATURE_DIR/plan.md
- TASKS = FEATURE_DIR/tasks.md
Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
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 Artifacts (Progressive Disclosure)
Load only the minimal necessary context from each artifact:
From spec.md:
- Overview/Context
- Functional Requirements
- Success Criteria (measurable outcomes — e.g., performance, security, availability, user success, business impact)
- User Stories
- Edge Cases (if present)
From plan.md:
- Architecture/stack choices
- Data Model references
- Phases
- Technical constraints
From tasks.md:
- Task IDs
- Descriptions
- Phase grouping
- Parallel markers [P]
- Referenced file paths
From constitution:
- Load
/memory/constitution.md for principle validation
3. Build Semantic Models
Create internal representations (do not include raw artifacts in output):
- Requirements inventory: For each Functional Requirement (FR-###) and Success Criterion (SC-###), record a stable key. Use the explicit FR-/SC- identifier as the primary key when present, and optionally also derive an imperative-phrase slug for readability (e.g., "User can upload file" →
user-can-upload-file). Include only Success Criteria items that require buildable work (e.g., load-testing infrastructure, security audit tooling), and exclude post-launch outcome metrics and business KPIs (e.g., "Reduce support tickets by 50%").
- User story/action inventory: Discrete user actions with acceptance criteria
- Task coverage mapping: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
- Constitution rule set: Extract principle names and MUST/SHOULD normative statements
4. Detection Passes (Token-Efficient Analysis)
Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
A. Duplication Detection
- Identify near-duplicate requirements
- Mark lower-quality phrasing for consolidation
B. Ambiguity Detection
- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
- Flag unresolved placeholders (TODO, TKTK, ???,
<placeholder>, etc.)
C. Underspecification
- Requirements with verbs but missing object or measurable outcome
- User stories missing acceptance criteria alignment
- Tasks referencing files or components not defined in spec/plan
D. Constitution Alignment
- Any requirement or plan element conflicting with a MUST principle
- Missing mandated sections or quality gates from constitution
E. Coverage Gaps
- Requirements with zero associated tasks
- Tasks with no mapped requirement/story
- Success Criteria requiring buildable work (performance, security, availability) not reflected in tasks
F. Inconsistency
- Terminology drift (same concept named differently across files)
- Data entities referenced in plan but absent in spec (or vice versa)
- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
5. Severity Assignment
Use this heuristic to prioritize findings:
- CRITICAL: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
- HIGH: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
- MEDIUM: Terminology drift, missing non-functional task coverage, underspecified edge case
- LOW: Style/wording improvements, minor redundancy not affecting execution order
6. Produce Compact Analysis Report
Output a Markdown report (no file writes) with the following structure:
Specification Analysis Report
| ID |
Category |
Severity |
Location(s) |
Summary |
Recommendation |
| A1 |
Duplication |
HIGH |
spec.md:L120-134 |
Two similar requirements ... |
Merge phrasing; keep clearer version |
(Add one row per finding; generate stable IDs prefixed by category initial.)
Coverage Summary Table:
| Requirement Key |
Has Task? |
Task IDs |
Notes |
Constitution Alignment Issues: (if any)
Unmapped Tasks: (if any)
Metrics:
- Total Requirements
- Total Tasks
- Coverage % (requirements with >=1 task)
- Ambiguity Count
- Duplication Count
- Critical Issues Count
7. Provide Next Actions
At end of report, output a concise Next Actions block:
- If CRITICAL issues exist: Recommend resolving before
speckit-implement
- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
- Provide explicit command suggestions: e.g., "Run speckit-specify with refinement", "Run speckit-plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
8. Offer Remediation
Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
9. Check for extension hooks
After reporting, check if .specify/extensions.yml exists in the project root.
- If it exists, read it and look for entries under the
hooks.after_analyze key
- If the YAML cannot be parsed or is invalid, do not skip silently: tell the user that
.specify/extensions.yml could not be read (include the parser error) and that no hooks were checked, including any mandatory (optional: false) hooks registered there, then 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
- 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}
After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal {command} id shown above, e.g. a skills-mode agent runs it as /skill:speckit-... or $speckit-...). Emitting the block alone does not run the hook.
- If no hooks are registered or
.specify/extensions.yml does not exist, skip silently
Operating Principles
Context Efficiency
- Minimal high-signal tokens: Focus on actionable findings, not exhaustive documentation
- Progressive disclosure: Load artifacts incrementally; don't dump all content into analysis
- Token-efficient output: Limit findings table to 50 rows; summarize overflow
- Deterministic results: Rerunning without changes should produce consistent IDs and counts
Analysis Guidelines
- NEVER modify files (this is read-only analysis)
- NEVER hallucinate missing sections (if absent, report them accurately)
- Prioritize constitution violations (these are always CRITICAL)
- Use examples over exhaustive rules (cite specific instances, not generic patterns)
- Report zero issues gracefully (emit success report with coverage statistics)
Context
$ARGUMENTS
Outputs and gates
Run pipelines-hook spec-standard first and treat its findings as the baseline: a row with no task line, a task naming no row, a behavior row with neither a bound test nor a test-spec entry, an orphan FR- or SC- label, an open clarification marker. Write specs/<stable-id>/checklists/analysis.md (lower case; plain bullets, no unchecked task boxes) with requirement-to-task-to-test coverage and end it with Pass, Fail or Needs revision and a coverage fraction. Fill specs/<stable-id>/checklists/requirements.md from .specify/templates/checklist-template.md; an unchecked item fails the gate. Report an unavailable tool or undefined threshold as a gap, never as a pass.
Workspace conventions
- Feature artifacts live in tracked repository-root
specs/<stable-id>/, never under .specify/specs/ or agent_data/. .specify/ holds only project configuration, templates and .specify/memory/constitution.md.
- Route the feature first with the ecosystem boundaries standard (https://github.com/Knuckles-Team/pipelines/blob/main/reference/ecosystem-boundaries.md). Each behavior has one normative owner. Look up the owning spec and extend it before you add a new one.
- Keep every requirement row ID (
<PREFIX>-<AREA>-R012.4), every Spec: commit trailer and every test binding intact. The delivery state (SPECIFIED, LANDED, VERIFIED, RETIRED) is computed by pipelines-hook spec-status; never write a Status: line or status.json.
- Specs and prompts name no private repository, internal host, homelab inventory or local workspace path. A contributor with only public GitHub access must be able to complete the work.
- When
.specify/scripts/ is absent, derive the feature directory from the repository root and the stable ID instead of running a script.
1---2name: speckit-analyze3domain: development4skill_type: skill5description: "Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation. Use after tasks.md exists to check spec, plan and tasks for consistency and gaps before implementing."6license: MIT7tags: [spec-kit, sdd, upstream]8metadata:9 source: https://skillmd.com/skills/knuckles-team/speckit-analyze10 version: '1.6.0'11 author: GitHub Spec Kit contributors12 upstream: https://github.com/github/spec-kit13---1415# speckit-analyze1617## User Input1819```text20$ARGUMENTS21```2223You **MUST** consider the user input before proceeding (if not empty).2425## Pre-Execution Checks2627**Check for extension hooks (before analysis)**:28- Check if `.specify/extensions.yml` exists in the project root.29- If it exists, read it and look for entries under the `hooks.before_analyze` key30- If the YAML cannot be parsed or is invalid, do not skip silently: tell the user that `.specify/extensions.yml` could not be read (include the parser error) and that no hooks were checked, including any mandatory (`optional: false`) hooks registered there, then continue normally31- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.32- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:33 - If the hook has no `condition` field, or it is null/empty, treat the hook as executable34 - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation35- For each executable hook, output the following based on its `optional` flag:36 - **Optional hook** (`optional: true`):37 ```38 ## Extension Hooks3940 **Optional Pre-Hook**: {extension}41 Command: `/{command}`42 Description: {description}4344 Prompt: {prompt}45 To execute: `/{command}`46 ```47 - **Mandatory hook** (`optional: false`):48 ```49 ## Extension Hooks5051 **Automatic Pre-Hook**: {extension}52 Executing: `/{command}`53 EXECUTE_COMMAND: {command}5455 Wait for the result of the hook command before proceeding to the Goal.56 ```57 After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal `{command}` id shown above, e.g. a skills-mode agent runs it as `/skill:speckit-...` or `$speckit-...`). Emitting the block alone does not run the hook.58- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently5960## Goal6162Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `speckit-tasks` has successfully produced a complete `tasks.md`.6364## Operating Constraints6566**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).6768**Constitution Authority**: The project constitution (`/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `speckit-analyze`.6970## Execution Steps7172### 1. Initialize Analysis Context7374Run `.specify/scripts/bash/check-prerequisites.sh --json --require-spec --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:7576- SPEC = FEATURE_DIR/spec.md77- PLAN = FEATURE_DIR/plan.md78- TASKS = FEATURE_DIR/tasks.md7980Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).81For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot").8283### 2. Load Artifacts (Progressive Disclosure)8485Load only the minimal necessary context from each artifact:8687**From spec.md:**8889- Overview/Context90- Functional Requirements91- Success Criteria (measurable outcomes — e.g., performance, security, availability, user success, business impact)92- User Stories93- Edge Cases (if present)9495**From plan.md:**9697- Architecture/stack choices98- Data Model references99- Phases100- Technical constraints101102**From tasks.md:**103104- Task IDs105- Descriptions106- Phase grouping107- Parallel markers [P]108- Referenced file paths109110**From constitution:**111112- Load `/memory/constitution.md` for principle validation113114### 3. Build Semantic Models115116Create internal representations (do not include raw artifacts in output):117118- **Requirements inventory**: For each Functional Requirement (FR-###) and Success Criterion (SC-###), record a stable key. Use the explicit FR-/SC- identifier as the primary key when present, and optionally also derive an imperative-phrase slug for readability (e.g., "User can upload file" → `user-can-upload-file`). Include only Success Criteria items that require buildable work (e.g., load-testing infrastructure, security audit tooling), and exclude post-launch outcome metrics and business KPIs (e.g., "Reduce support tickets by 50%").119- **User story/action inventory**: Discrete user actions with acceptance criteria120- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)121- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements122123### 4. Detection Passes (Token-Efficient Analysis)124125Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.126127#### A. Duplication Detection128129- Identify near-duplicate requirements130- Mark lower-quality phrasing for consolidation131132#### B. Ambiguity Detection133134- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria135- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)136137#### C. Underspecification138139- Requirements with verbs but missing object or measurable outcome140- User stories missing acceptance criteria alignment141- Tasks referencing files or components not defined in spec/plan142143#### D. Constitution Alignment144145- Any requirement or plan element conflicting with a MUST principle146- Missing mandated sections or quality gates from constitution147148#### E. Coverage Gaps149150- Requirements with zero associated tasks151- Tasks with no mapped requirement/story152- Success Criteria requiring buildable work (performance, security, availability) not reflected in tasks153154#### F. Inconsistency155156- Terminology drift (same concept named differently across files)157- Data entities referenced in plan but absent in spec (or vice versa)158- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)159- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)160161### 5. Severity Assignment162163Use this heuristic to prioritize findings:164165- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality166- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion167- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case168- **LOW**: Style/wording improvements, minor redundancy not affecting execution order169170### 6. Produce Compact Analysis Report171172Output a Markdown report (no file writes) with the following structure:173174## Specification Analysis Report175176| ID | Category | Severity | Location(s) | Summary | Recommendation |177|----|----------|----------|-------------|---------|----------------|178| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |179180(Add one row per finding; generate stable IDs prefixed by category initial.)181182**Coverage Summary Table:**183184| Requirement Key | Has Task? | Task IDs | Notes |185|-----------------|-----------|----------|-------|186187**Constitution Alignment Issues:** (if any)188189**Unmapped Tasks:** (if any)190191**Metrics:**192193- Total Requirements194- Total Tasks195- Coverage % (requirements with >=1 task)196- Ambiguity Count197- Duplication Count198- Critical Issues Count199200### 7. Provide Next Actions201202At end of report, output a concise Next Actions block:203204- If CRITICAL issues exist: Recommend resolving before `speckit-implement`205- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions206- Provide explicit command suggestions: e.g., "Run speckit-specify with refinement", "Run speckit-plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"207208### 8. Offer Remediation209210Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)211212### 9. Check for extension hooks213214After reporting, check if `.specify/extensions.yml` exists in the project root.215- If it exists, read it and look for entries under the `hooks.after_analyze` key216- If the YAML cannot be parsed or is invalid, do not skip silently: tell the user that `.specify/extensions.yml` could not be read (include the parser error) and that no hooks were checked, including any mandatory (`optional: false`) hooks registered there, then continue normally217- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.218- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:219 - If the hook has no `condition` field, or it is null/empty, treat the hook as executable220 - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation221- For each executable hook, output the following based on its `optional` flag:222 - **Optional hook** (`optional: true`):223 ```224 ## Extension Hooks225226 **Optional Hook**: {extension}227 Command: `/{command}`228 Description: {description}229230 Prompt: {prompt}231 To execute: `/{command}`232 ```233 - **Mandatory hook** (`optional: false`):234 ```235 ## Extension Hooks236237 **Automatic Hook**: {extension}238 Executing: `/{command}`239 EXECUTE_COMMAND: {command}240 ```241 After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal `{command}` id shown above, e.g. a skills-mode agent runs it as `/skill:speckit-...` or `$speckit-...`). Emitting the block alone does not run the hook.242- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently243244## Operating Principles245246### Context Efficiency247248- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation249- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis250- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow251- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts252253### Analysis Guidelines254255- **NEVER modify files** (this is read-only analysis)256- **NEVER hallucinate missing sections** (if absent, report them accurately)257- **Prioritize constitution violations** (these are always CRITICAL)258- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)259- **Report zero issues gracefully** (emit success report with coverage statistics)260261## Context262263$ARGUMENTS264265## Outputs and gates266267Run `pipelines-hook spec-standard` first and treat its findings as the baseline: a row with no task line, a task naming no row, a behavior row with neither a bound test nor a test-spec entry, an orphan `FR-` or `SC-` label, an open clarification marker. Write `specs/<stable-id>/checklists/analysis.md` (lower case; plain bullets, no unchecked task boxes) with requirement-to-task-to-test coverage and end it with **Pass**, **Fail** or **Needs revision** and a coverage fraction. Fill `specs/<stable-id>/checklists/requirements.md` from `.specify/templates/checklist-template.md`; an unchecked item fails the gate. Report an unavailable tool or undefined threshold as a gap, never as a pass.268269## Workspace conventions270271- Feature artifacts live in tracked repository-root `specs/<stable-id>/`, never under `.specify/specs/` or `agent_data/`. `.specify/` holds only project configuration, templates and `.specify/memory/constitution.md`.272- Route the feature first with the ecosystem boundaries standard (https://github.com/Knuckles-Team/pipelines/blob/main/reference/ecosystem-boundaries.md). Each behavior has one normative owner. Look up the owning spec and extend it before you add a new one.273- Keep every requirement row ID (`<PREFIX>-<AREA>-R012.4`), every `Spec:` commit trailer and every test binding intact. The delivery state (`SPECIFIED`, `LANDED`, `VERIFIED`, `RETIRED`) is computed by `pipelines-hook spec-status`; never write a `Status:` line or `status.json`.274- Specs and prompts name no private repository, internal host, homelab inventory or local workspace path. A contributor with only public GitHub access must be able to complete the work.275- When `.specify/scripts/` is absent, derive the feature directory from the repository root and the stable ID instead of running a script.