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

> Learn how speckit analyze ensures cross-artifact consistency by validating spec.md plan.md and tasks.md before implementation. Prevent untracked requirements and unsupported tasks.

- Repository: [GitHub/spec-kit](https://github.com/github/spec-kit)
- Tags: internals
- Published: 2026-03-05

---

**/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)](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)](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`](https://github.com/github/spec-kit/blob/main/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`](https://github.com/github/spec-kit/blob/main/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)](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:

```bash

# 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:

```bash
$ 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:

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

```

Request remediation suggestions interactively:

```bash
$ 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`](https://github.com/github/spec-kit/blob/main/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`](https://github.com/github/spec-kit/blob/main/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`](https://github.com/github/spec-kit/blob/main/src/specify_cli/__init__.py) maps the `/speckit.analyze` invocation to [`templates/commands/analyze.md`](https://github.com/github/spec-kit/blob/main/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.