speckit.analyze — Claude Code prompt: cross-artifact spec check
speckit.analyze runs a read-only pass over spec.md, plan.md and tasks.md, then prints a report on contradictions, duplicates and requirements that no task covers.
MIT ★ 110 updated 2026-10-19
.claude/commands/speckit.analyze.mdWhat speckit.analyze does
The command wants a finished feature folder. spec.md, plan.md and a complete tasks.md all have to exist; fire it before /speckit.tasks and it stops with an error telling you which step to run first.
It starts with .specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks from the repo root to find the feature directory and its documents. Then it builds an inventory of requirements with stable keys, maps each task back to a requirement or user story, and runs six checks: near-duplicate requirements, vague adjectives with no measurable criteria, leftover placeholders, constitution conflicts, requirements with zero tasks, terminology drift between files.
Nothing on disk changes. You get a findings table with severity, location and a suggested fix, plus a coverage table and counts, capped at 50 rows. Anything clashing with a MUST rule in .specify/memory/constitution.md is marked CRITICAL and has to be settled in the spec, plan or tasks — the principle itself stays put. Edits happen only if you ask for them.
What it helps with
- Catch a requirement in
spec.mdthat no task implements - Spot a stack mismatch between
plan.mdand the spec - Collect duplicate and vague requirements in one report before coding
- Check the plan against the project constitution
- List tasks that trace back to no requirement or user story
Example prompts for the agent
/speckit.analyze— check the 003-payments artifacts before I start coding- Run
/speckit.analyzeand show me which requirements have no tasks /speckit.analyzewith focus on constitution conflicts
How to install speckit.analyze
Manually: put the files in place
.claude/commands/speckit.analyze.mdHow to use
Paste the text at the start of a chat or into project instructions
Questions about speckit.analyze
How do I install speckit.analyze in Claude Code?
Place the command file at .claude/commands/speckit.analyze.md in your project. It then shows up as /speckit.analyze.
What does speckit.analyze do?
It compares the three artifacts and prints a severity-ranked report on inconsistencies, duplicates, ambiguity and coverage gaps. Your files stay untouched.
When should I run it?
Once /speckit.tasks has written a complete tasks.md, and before implementation. A missing artifact makes the command abort and name the step you skipped.
Source text
speckit.analyze.md · MIT
--- description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation. --- ## User Input ```text $ARGUMENTS ``` You **MUST** consider the user input before proceeding (if not empty). ## 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 (`.specify/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-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 - Non-Functional Requirements - 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 `.specify/memory/constitution.md` for principle validation ### 3. Build Semantic Models Create internal representations (do not include raw artifacts in output): - **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`) - **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 - Non-functional requirements not reflected in tasks (e.g., performance, security) #### 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.) ## 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
© alfredoperez · MIT · alfredoperez/speckit-companion