speckit-analyze

User Input

$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

READ-ONLY w.r.t. inputs: Do not modify spec.md, plan.md, tasks.md, constitution.md, or any other artifact under FEATURE_DIR/. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).

Exception — persisted analyze report: The skill writes a single managed file at FEATURE_DIR/.specify/analyze-report.md containing the report plus a pin block recording the spec/plan/tasks hashes the analysis was run against. The build-order scanner reads this file to detect when an analyze run has gone stale (i.e., spec/plan/tasks have changed since analyze last ran). This persistence is intentional and is the only file /speckit-analyze is permitted to write.

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

If any required file is missing, use AskUserQuestion to surface the error and tell the user which prerequisite skill to run manually. Do not invoke any skill automatically. 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
• Success Criteria (measurable outcomes — e.g., performance, security, availability, user success, business impact)
• 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: For each Functional Requirement (FR-###) and Success Criterion (SC-###), record a stable key. Use the explicit FR-/SC- identifier as the primary key when present, and optionally also derive an imperative-phrase slug for readability (e.g., "User can upload file" → user-can-upload-file). Include only Success Criteria items that require buildable work (e.g., load-testing infrastructure, security audit tooling), and exclude post-launch outcome metrics and business KPIs (e.g., "Reduce support tickets by 50%").
• 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
• Success Criteria requiring buildable work (performance, security, availability) not reflected in tasks

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

Use AskUserQuestion to ask: "Would you like me to suggest concrete remediation edits for the top N issues?"

Do NOT apply remediations automatically. If CRITICAL issues exist, bias any remediation recommendations toward the most ambitious, complete, enterprise-grade resolution — never toward deferring, narrowing scope, or accepting reduced quality.

9. Persist analyze report with pin block

After producing the analysis report, write it to a managed file so /build-order can detect when an analyze run has gone stale. The report file lives at FEATURE_DIR/.specify/analyze-report.md and contains:

1. The same Markdown report that was emitted to the user (Specification Analysis Report table, Coverage Summary, Constitution Alignment Issues, Unmapped Tasks, Metrics, Next Actions)
2. A pin block at the top recording spec.md, plan.md, and tasks.md blob hashes at analysis time

Run from repo root after writing the report body. The first two lines below are illustrative — the model writes analyze-report.md directly via its file-edit tool with the same Markdown body it emitted to the user; the third line is a literal bash invocation:

mkdir -p "$FEATURE_DIR/.specify"
# (model writes $FEATURE_DIR/.specify/analyze-report.md via Write tool with the report body)
bash scripts/build-order/backfill-pins.sh --spec "$FEATURE_DIR"

The backfill helper detects .specify/analyze-report.md and pins it against the current spec.md/plan.md/tasks.md hashes. Idempotent. The persisted report serves as both the audit trail of what was found and the staleness signal for /build-order's ## Stale artifacts section.

Persist output: Ensure analyze-report.md is written to disk via the Write tool and committed (git add + git commit + git push). No report content should exist only in context.

Handoff: After persisting the report, use AskUserQuestion to say: "Analysis complete. Type /speckit-implement to begin implementation."

Do not invoke /speckit-implement yourself. The user must type the command.

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)

Anti-criteria

• MUST NOT modify spec.md, plan.md, tasks.md, constitution.md, or any artifact under FEATURE_DIR/ — analysis is strictly read-only (the only permitted write is analyze-report.md)
• MUST NOT apply remediations automatically — user must explicitly approve any follow-up edits (Step 8)
• MUST NOT invoke any prerequisite skill automatically when required files are missing (Step 1)
• MUST NOT invoke /speckit-implement via the Skill tool or any other mechanism — the user must type the command themselves (Handoff)
• MUST NOT dilute, reinterpret, or silently ignore constitution principles — constitution conflicts are always CRITICAL (Step 4D)
• MUST NOT recommend deferring or narrowing scope as a remediation — bias toward ambitious, complete, enterprise-grade resolution

Context

$ARGUMENTS