How /speckit.analyze Performs Cross-Artifact Consistency Analysis in Spec-Kit

/speckit.analyze is a read-only command that validates the coherence of spec.md, plan.md, and tasks.md before implementation begins, ensuring no requirement goes untracked and no task lacks specification backing.

The github/spec-kit repository implements this verification through a declarative template system rather than hardcoded logic, making the analysis pipeline extensible and deterministic. By scanning across the three core artifacts—specifications, plans, and generated tasks—the command detects duplication gaps, constitutional violations, and coverage inconsistencies before a single line of implementation code is written.

Declarative Command Definition

Unlike traditional CLI tools that embed logic in Python modules, /speckit.analyze derives its behavior from the declarative template at [templates/commands/analyze.md](https://github.com/github/spec-kit/blob/main/templates/commands/analyze.md). This template defines the entire workflow—from prerequisite checks to severity heuristics—allowing the analysis logic to evolve without modifying the CLI source code.

The command registers itself with the Spec-Kit CLI through the command-registry in [src/specify_cli/__init__.py](https://github.com/github/spec-kit/blob/main/src/specify_cli/__init__.py). When invoked, the CLI resolves the command name to its template, executes the prerequisite shell scripts (check-prerequisites.sh or check-prerequisites.ps1), and injects the repository root into the template’s {SCRIPT} placeholder.

The 8-Stage Analysis Pipeline

The cross-artifact consistency analysis operates as a deterministic, eight-stage pipeline defined in lines 30-168 of the analyze template. Each stage progressively builds a semantic understanding of the project state before emitting findings.

Stage 1: Initialize Analysis Context

The pipeline begins by parsing the JSON output of the prerequisite script to locate the three mandatory artifacts. If spec.md, plan.md, or tasks.md is missing, the command aborts immediately rather than proceeding with partial data (lines 30-35).

Stage 2: Load Artifacts via Progressive Disclosure

Rather than ingesting entire files, the analyzer performs progressive disclosure—extracting only high-signal sections from each artifact. It pulls overviews, functional and non-functional requirements, user stories, implementation phases, and task IDs (lines 41-65). This targeted extraction keeps token usage low while preserving semantic relevance.

Stage 3: Build Semantic Models

With the relevant sections loaded, the command constructs in-memory inventories (lines 70-78):

• Requirements registry: All functional and non-functional requirements from spec.md
• User-story action maps: Extracted behaviors and actor intentions
• Task-coverage maps: Bidirectional links between tasks and requirements
• Constitution rule set: Constraints and policies that govern the specification

Stage 4: Detection Passes

The analyzer executes a series of focused scans (lines 79-116):

• Duplication detection: Identical or near-identical requirements across artifacts
• Ambiguity analysis: Vague language lacking measurable criteria
• Underspecification checks: Requirements without acceptance criteria
• Constitution alignment: Violations of project-specific governance rules
• Coverage gap identification: Requirements lacking implementation tasks
• Cross-artifact inconsistency: Logical contradictions between spec, plan, and tasks

To maintain token efficiency, the scanner caps findings at 50 issues, prioritizing the most severe discrepancies.

Stage 5: Severity Assignment

Each finding receives a deterministic severity classification (lines 117-124):

• CRITICAL: Constitution violations or logical contradictions that block implementation
• HIGH: Significant coverage gaps or duplicated efforts
• MEDIUM: Ambiguity or minor inconsistency
• LOW: Style deviations or optional refinements

The severity heuristic is hardcoded in the template, ensuring consistent prioritization across different projects.

Stage 6: Produce Compact Analysis Report

The command emits a structured Markdown report containing (lines 126-155):

• A findings table with Category, Severity, Location, Summary, and Recommendation columns
• A coverage-summary table showing requirement-to-task mapping percentages
• Constitution-alignment notes detailing policy adherence
• Warnings for unmapped tasks
• High-level metrics including total requirements and coverage percentage

Stage 7: Next-Action Recommendations

Based on the severity distribution, the analyzer suggests concrete next steps (lines 156-163). If CRITICAL issues exist, it explicitly blocks progression to /speckit.implement until resolution. For lower-severity findings, it offers optional refinement workflows.

Stage 8: Optional Remediation Offer

The final stage prompts the user to request concrete edit suggestions (lines 164-168). Importantly, because the command declares itself **STRICTLY READ-ONLY** in the template, it never modifies files automatically—any remediation requires explicit user approval through subsequent commands.

CLI Integration and Execution

The generic command-loader in src/specify_cli/__init__.py binds the template to the executable command at runtime. This architecture means adding new analysis capabilities requires only template modifications, not Python redeployment.

Helper utilities in [src/specify_cli/extensions.py](https://github.com/github/spec-kit/blob/main/src/specify_cli/extensions.py) provide underlying support through functions like check_tool and run_script, which the prerequisite scripts invoke before the main analysis begins.

Running the Analysis

Execute the command as part of the standard Spec-Kit workflow:

# Complete workflow example

specify init --ai opencode          # Bootstrap project structure

specify spec                        # Author spec.md

specify plan                        # Create implementation plan.md

specify tasks                       # Generate tasks.md

specify analyze                     # Validate cross-artifact consistency

Direct invocation triggers the full analysis pipeline:

$ speckit.analyze

## Specification Analysis Report

| ID | Category    | Severity | Location(s)      | Summary                                   | Recommendation |
|----|-------------|----------|------------------|-------------------------------------------|----------------|
| D1 | Duplication | HIGH     | spec.md:L120-134 | Two near-identical upload-file requirements | Merge phrasing |
...

When critical issues exist, the CLI intervenes:

❗ CRITICAL: Constitution rule "All data must be encrypted at rest" is violated …
→ Resolve before running /speckit.implement

Request remediation suggestions interactively:

$ speckit.analyze
Would you like me to suggest concrete remediation edits for the top 3 issues? (y/n)

Summary

• Declarative architecture: Analysis logic lives in templates/commands/analyze.md, not Python code, enabling rapid iteration without redeployment.
• Three-artifact validation: The command specifically validates consistency between spec.md, plan.md, and tasks.md.
• Token-efficient scanning: Progressive disclosure loads only relevant sections, capping findings at 50 to manage context window usage.
• Deterministic severity: CRITICAL/HIGH/MEDIUM/LOW classifications follow fixed heuristics, with constitution violations automatically receiving CRITICAL status.
• Read-only guarantee: The template’s **STRICTLY READ-ONLY** declaration ensures analysis never modifies source files, maintaining repository safety.

Frequently Asked Questions

What files does /speckit.analyze actually examine?

The command examines three core artifacts located in the repository root: spec.md (requirements and constraints), plan.md (implementation phases and strategy), and tasks.md (generated task list). If any file is missing, the analysis aborts at the initialization stage (lines 30-35 in templates/commands/analyze.md).

Why is the analysis limited to 50 findings?

The 50-finding cap manages token consumption during the detection passes (lines 79-116). By limiting output to the highest-priority issues, the command prevents context window overflow in AI-assisted workflows while ensuring developers address the most severe inconsistencies first.

Can /speckit.analyze fix the issues it finds?

No. The command is explicitly declared as **STRICTLY READ-ONLY** in its template definition. While it offers to generate concrete remediation suggestions upon user request (lines 164-168), it never writes changes to disk. All fixes must be applied through subsequent commands or manual edits.

How does the CLI know which template to execute for /speckit.analyze?

The command registry in src/specify_cli/__init__.py maps the /speckit.analyze invocation to templates/commands/analyze.md at runtime. This registry scans the templates/commands/ directory dynamically, allowing new analysis commands to be added by creating new template files without modifying the CLI source code.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}