analyze

Analyze Specification Artifacts

You are performing a read-only, non-destructive quality analysis across all specification artifacts for a feature. You identify issues but NEVER modify files.

Upstream source: github/spec-kit

Prerequisites

• At minimum, specs/[###-feature-name]/spec.md must exist
• For full analysis, plan.md and tasks.md should also exist
• Run this command AFTER /spec-kit:tasks has produced a complete tasks.md for full coverage analysis

Workflow

Step 1: Identify the Feature

• If the user specifies a feature name/number, locate it in specs/
• If multiple features exist and none is specified, list available features and ask the user to choose
• If only one feature exists, use it automatically

Step 2: Load All Available Artifacts

Load only the minimal necessary context from each artifact (progressive disclosure):

From spec.md: Overview/Context, Functional Requirements, Success Criteria, User Stories, Edge Cases

From plan.md: Architecture/stack choices, Data Model references, Technical constraints

From tasks.md: Task IDs, descriptions, phase grouping, parallel markers [P], referenced file paths

From constitution: Load .speckit/constitution.md for principle validation

Report what was loaded:

Artifacts Loaded:
  [x] spec.md
  [x] plan.md
  [ ] tasks.md (not found — coverage analysis will be limited)
  [x] constitution.md

Step 3: Build Semantic Models

Create internal representations (not output):

• Requirements inventory: For each FR-### and SC-###, record ID and semantic key
  • Include only SC-### items that require buildable work (load-testing infrastructure, security audit tooling)
  • Exclude post-launch outcome metrics and business KPIs
• User story/action inventory: Discrete user actions with acceptance criteria
• Task coverage mapping: Map each task to one or more requirements or stories
• Constitution rule set: Extract principle names and MUST/SHOULD normative statements

Step 4: Detection Passes (max 50 findings total)

A. Duplication Detection

• Near-duplicate requirements
• Redundant user stories or acceptance criteria
• Mark lower-quality phrasing for consolidation

B. Ambiguity Detection

• Vague adjectives lacking measurable criteria: fast, scalable, secure, intuitive, robust
• Unresolved placeholders: TODO, TKTK, ???, <placeholder>, [NEEDS CLARIFICATION]
• Requirements with verbs but missing object or measurable outcome

C. Underspecification

• Requirements with verbs but missing objects
• User stories missing acceptance criteria alignment
• Tasks referencing files or components not defined in spec/plan

D. Constitution Alignment

• Constitution violations are ALWAYS CRITICAL
• Any requirement or plan element conflicting with a MUST principle
• Missing mandated sections or quality gates from constitution

E. Coverage Gaps

• Orphaned requirements: FR-### with zero associated tasks
• Orphaned tasks: Tasks with no mapped requirement/story
• Success Criteria gaps: SC-### requiring buildable work not reflected in tasks (performance, security, availability)

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
• Conflicting requirements (e.g., one requires Next.js while other specifies Vue)

Step 5: Severity Assignment

• CRITICAL: Violates constitution MUST, missing core spec artifact, requirement with zero coverage blocking 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

Step 6: Generate Compact Analysis Report

Output a Markdown report (do NOT write to any file):

# Specification Analysis Report: [FEATURE NAME]

**Date**: [TODAY] | **Artifacts Analyzed**: [count]

## Findings

| ID | Category | Severity | Location(s) | Summary | Recommendation |
|----|----------|----------|-------------|---------|----------------|
| A1 | Ambiguity | HIGH | spec.md §Requirements | Vague term "fast" in FR-003 | Add measurable latency target (e.g., "under 200ms") |
| C1 | Coverage | MEDIUM | tasks.md | FR-005 has no corresponding task | Add task for FR-005 implementation |

## Coverage Summary

| Requirement Key | Has Task? | Task IDs | Notes |
|-----------------|-----------|----------|-------|
| FR-001 | ✅ Yes | T005, T006 | |
| FR-002 | ❌ No | — | No implementation task found |

### User Story Coverage
| Story | Tasks | Independent Test | Status |
|-------|-------|-----------------|--------|
| US1 (P1) | T010-T013 | ✅ Defined | Full |
| US2 (P2) | T014-T016 | ⚠️ Missing | Gap |

## Constitution Alignment
[PASS/FAIL per principle with specific notes if any violation]

## Metrics

- Total Requirements: [N]
- Total Tasks: [N]
- Coverage %: [N]% (requirements with ≥1 task)
- Ambiguity Count: [N]
- Duplication Count: [N]
- Critical Issues: [N]
- Estimated Rework Risk: [Low/Medium/High]

Step 7: Next Actions

At end of report, output a concise Next Actions block:

• If CRITICAL issues: Recommend resolving before /spec-kit:implement
• If only LOW/MEDIUM: User may proceed, with improvement suggestions
• Provide explicit command suggestions: e.g., "Run /spec-kit:clarify to resolve FR-003 ambiguity"

Step 8: Offer Remediation

Ask: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply automatically — user must explicitly approve and manually run the relevant commands.)

Operating Principles

• STRICTLY READ-ONLY: Never modify any files
• Prioritize constitution violations: These are always CRITICAL
• Be specific: Cite exact requirement IDs, section headers, quoted text
• Maximum 50 findings: Aggregate remaining in overflow summary
• Deterministic: Rerunning without changes should produce consistent IDs and counts
• Don't flag style preferences — focus on substantive issues affecting implementation correctness