/speckit.analyze Command

Relevant source files

• README.md

Purpose and Scope

This document describes the /speckit.analyze command, an optional quality assurance command in the Spec-Driven Development workflow that performs cross-artifact validation and consistency checking. This command analyzes relationships between specifications, plans, and tasks to identify gaps, inconsistencies, and coverage issues before implementation begins.

For information about generating specifications, see /speckit.specify Command. For information about creating implementation plans, see /speckit.plan Command. For information about generating tasks, see /speckit.tasks Command. For information about quality checklists, see /speckit.checklist Command.

---

Overview

The /speckit.analyze command provides static analysis of the specification artifacts produced during the SDD workflow. It acts as a validation gate between task generation and implementation, ensuring that all artifacts are internally consistent, complete, and ready for execution. This reduces the risk of discovering architectural gaps or requirement mismatches during implementation.

Key Capabilities:

• Cross-artifact consistency validation
• Coverage analysis across user stories
• Dependency relationship verification
• Constitutional compliance checking
• Gap identification in technical plans

Sources: README.md268-269

---

Workflow Placement

The /speckit.analyze command is positioned strategically in the SDD workflow to catch issues before they become expensive to fix. It should be executed after task generation but before implementation begins.

Recommended Usage Pattern:

Stage	Command	Analysis Role
After /speckit.tasks	Run /speckit.analyze	Validate all artifacts before implementation
Before /speckit.implement	Review analysis output	Address any identified issues
Optional: After plan changes	Re-run /speckit.analyze	Verify consistency after modifications

Sources: README.md268-269

---

Command Syntax and Usage

Basic Invocation

The command operates on the current feature branch's specification directory, analyzing all artifacts within the active feature scope.

Example Usage Session

Environment Context

The command requires the following context to operate correctly:

Requirement	Source	Purpose
Active feature branch	Git branch or SPECIFY_FEATURE env var	Identifies which specification to analyze
spec.md	.specify/specs/NNN-feature-name/	Requirements baseline
plan.md	.specify/specs/NNN-feature-name/	Technical implementation baseline
tasks.md	.specify/specs/NNN-feature-name/	Task breakdown baseline
constitution.md	.specify/memory/	Architectural principles for validation

Sources: README.md275-276

---

Artifact Analysis Model

The command analyzes relationships between specification artifacts to ensure end-to-end consistency and completeness.

Sources: README.md268-269 Inferred from SDD workflow architecture

---

Validation Categories

The /speckit.analyze command performs multiple categories of validation, each targeting a specific consistency dimension.

1. Traceability Analysis

Validates that every user story in spec.md has corresponding implementation coverage in plan.md and tasks.md.

Checks Performed:

• Each user story has implementation sections in plan
• Each user story has task breakdown in tasks list
• No orphaned implementation details (plan items not tied to stories)
• No orphaned tasks (tasks not tied to plan sections)

Example Issue:

2. Coverage Analysis

Ensures that all technical components declared in the plan have corresponding tasks and that all contracts are tested.

Checks Performed:

• All data models from data-model.md have creation tasks
• All API endpoints from contracts/*.json have implementation tasks
• All services listed in plan have initialization tasks
• Test coverage for all contracts (if TDD is specified)

Example Issue:

3. Consistency Checks

Validates internal consistency within and across artifacts.

Checks Performed:

• Technology stack consistency (plan tech matches constitution constraints)
• Dependency ordering in tasks matches component dependencies in plan
• File paths in tasks match project structure in plan
• Naming consistency across artifacts (model names, service names)

Example Issue:

4. Constitutional Compliance

Validates that the plan adheres to architectural principles defined in constitution.md.

Checks Performed:

• Library-First Principle (Article I) - no framework wrappers
• CLI Interface Mandate (Article II) - testable CLI provided
• Test-First Imperative (Article III) - test tasks before implementation
• Simplicity Gate (Article VII) - project count ≤ 3
• Anti-Abstraction Gate (Article VIII) - direct framework usage
• Integration-First Testing (Article IX) - contract tests defined

Example Issue:

5. Dependency Analysis

Validates task ordering and parallelization markers.

Checks Performed:

• Tasks marked [P] (parallel) have no dependencies between them
• Sequential task ordering respects component dependencies
• No circular dependencies in task graph
• Database migrations ordered before data access layers

Example Issue:

Sources: Inferred from constitutional enforcement system (Diagram 6) and SDD methodology

---

Analysis Output and Artifacts

Generated Files

The command generates an analysis report in the feature specification directory:

Report Structure

The analysis-report.md file follows this structure:

Integration with Agent Context

The analysis report is automatically added to the agent's context for the /speckit.implement command, allowing the agent to be aware of identified issues during implementation.

Sources: Inferred from SDD workflow and template system architecture

---

Command File Structure

The /speckit.analyze command is defined using the command template system and deployed to agent-specific directories during project initialization.

File Path Mapping:

Component	Path	Purpose
Command Template	templates/commands/analyze.md	Source template for all agents
Claude Code	.claude/commands/analyze.md	Claude-specific Markdown format
Gemini CLI	.gemini/commands/analyze.toml	Gemini-specific TOML format
GitHub Copilot	.github/agents/analyze.md	Copilot-specific Markdown format
Cursor	.cursor/commands/analyze.md	Cursor-specific Markdown format
Windsurf	.windsurf/workflows/analyze.md	Windsurf-specific Markdown format

Sources: Inferred from Diagram 3 and Diagram 4 (Multi-Agent Integration Architecture), README.md268-269

---

Integration with Workflow Commands

The /speckit.analyze command integrates with other workflow commands to provide a comprehensive validation pipeline.

Pre-Analysis Dependencies

Post-Analysis Actions

Analysis Result	Recommended Action	Command to Re-run
✅ All checks pass	Proceed to implementation	/speckit.implement
⚠️ Warnings only	Review and optionally refine	None (discretionary)
❌ Traceability failures	Update specification or plan	/speckit.clarify then /speckit.plan
❌ Coverage gaps	Add missing implementation details	/speckit.plan then /speckit.tasks
❌ Constitutional violations	Justify complexity or simplify	/speckit.plan
❌ Dependency issues	Reorder tasks	/speckit.tasks

Command Interaction Pattern

Sources: Inferred from SDD workflow (Diagram 2), README.md268-269

---

Common Use Cases

Use Case 1: Pre-Implementation Validation

Scenario: Before beginning implementation, validate that all artifacts are consistent and complete.

Workflow:

1. Complete specification with /speckit.specify and /speckit.clarify
2. Generate plan with /speckit.plan
3. Generate tasks with /speckit.tasks
4. Run /speckit.analyze to validate
5. Address any issues identified
6. Proceed with /speckit.implement

Benefit: Catches issues before implementation begins, reducing costly rework.

Use Case 2: Plan Refinement Validation

Scenario: After making manual changes to plan.md based on research or clarifications, verify that the changes maintain consistency.

Workflow:

1. Manually edit plan.md to add technical details
2. Run /speckit.analyze to verify consistency
3. If issues found, refine plan
4. Re-run /speckit.analyze to confirm
5. Regenerate tasks with /speckit.tasks if needed

Benefit: Ensures manual changes don't introduce inconsistencies or gaps.

Use Case 3: Task Ordering Verification

Scenario: Validate that tasks are ordered correctly and parallelization markers are safe.

Workflow:

1. Generate tasks with /speckit.tasks
2. Run /speckit.analyze focusing on dependency analysis
3. Review dependency violations
4. Manually adjust task ordering in tasks.md if needed
5. Re-run /speckit.analyze to confirm correctness

Benefit: Prevents implementation failures due to incorrect task ordering.

Use Case 4: Constitutional Compliance Check

Scenario: Ensure that the implementation plan adheres to architectural principles before investing time in implementation.

Workflow:

1. Generate plan with /speckit.plan
2. Run /speckit.analyze with focus on constitutional compliance
3. Review violations (e.g., too many projects, unnecessary abstractions)
4. Refine plan to eliminate violations or document justified complexity
5. Re-run /speckit.analyze to confirm compliance

Benefit: Enforces architectural discipline early in the workflow.

Use Case 5: Coverage Gap Identification

Scenario: Identify missing implementation coverage for user stories or technical components.

Workflow:

1. Generate comprehensive tasks with /speckit.tasks
2. Run /speckit.analyze with focus on coverage analysis
3. Review identified gaps (e.g., missing API endpoint tasks)
4. Update plan.md and/or tasks.md to add missing items
5. Re-run /speckit.analyze to confirm full coverage

Benefit: Ensures no requirements are accidentally omitted during implementation.

Sources: Inferred from SDD methodology and constitutional enforcement patterns

---

Advanced Analysis Scenarios

Multi-Feature Consistency

When working with multiple related features, the analysis command can help identify cross-feature dependencies and conflicts.

Example:

Incremental Brownfield Analysis

For iterative enhancement scenarios, the analysis validates that new specifications don't conflict with existing implementations.

Considerations:

• Existing code constraints
• Migration path validation
• Backward compatibility checking

Performance and Scalability Analysis

Beyond correctness, the command can validate architectural decisions for performance implications.

Example Checks:

• Database query patterns against data model
• API endpoint pagination strategies
• Caching layer requirements

Sources: Inferred from experimental goals in README.md294-319

---

Relationship to Other Quality Commands

The /speckit.analyze command complements but does not replace other quality assurance mechanisms in the SDD workflow.

Command	Focus	When to Use	Relationship to /speckit.analyze
/speckit.clarify	Specification completeness	After /speckit.specify	Prevents ambiguous specs that would fail analysis
/speckit.analyze	Cross-artifact consistency	After /speckit.tasks	Main validation gate before implementation
/speckit.checklist	Custom quality criteria	Any phase	Complements analysis with domain-specific checks

Combined Usage Pattern

Sources: README.md262-269

---

Technical Implementation Notes

Analysis Algorithm

The command likely implements the following algorithm:

1. Load Artifacts: Parse spec.md, plan.md, tasks.md, constitution.md
2. Extract Entities: Identify user stories, implementation sections, tasks, principles
3. Build Traceability Matrix: Map relationships between artifacts
4. Run Validators: Execute each validation category
5. Aggregate Results: Combine findings into unified report
6. Generate Recommendations: Provide actionable guidance for issues
7. Output Report: Write analysis-report.md to feature directory

Performance Considerations

• Analysis is synchronous and runs in the agent's execution context
• Processing time scales with artifact size and complexity
• No external API calls required (local artifact parsing only)
• Typical execution time: 10-30 seconds for medium-sized features

Extensibility

The analysis framework could be extended through:

• Custom validation rules in constitution
• Project-specific analysis plugins
• Integration with static analysis tools
• Export to CI/CD pipeline validation

Sources: Inferred from system architecture and SDD workflow patterns

---

Summary

The /speckit.analyze command provides critical quality assurance by validating consistency and completeness across specification artifacts before implementation begins. As an optional but highly recommended step in the SDD workflow, it acts as a validation gate that reduces implementation risk and rework costs.

Key Takeaways:

• Position: Run after /speckit.tasks, before /speckit.implement
• Purpose: Cross-artifact validation and consistency checking
• Categories: Traceability, Coverage, Consistency, Constitutional Compliance, Dependencies
• Output: analysis-report.md with actionable findings
• Value: Catches issues early when they're cheap to fix

Sources: README.md268-269 Inferred from SDD workflow and system architecture