speckit-analyze

name	speckit-analyze
description	Perform a non-destructive cross-artifact consistency, quality analysis, and validation across spec.md, plan.md, and open beads (via br/bv).
compatibility	Requires spec-kit project structure with .specify/ directory and Beads issue tracker
metadata	{"author":"github-spec-kit","source":"templates/commands/analyze.md"}

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Pre-Execution Checks

Check for extension hooks (before analysis):

• Check if .specify/extensions.yml exists in the project root.
• If it exists, read it and look for entries under the hooks.before_analyze key
• If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
• Filter out hooks where enabled is explicitly false. Treat hooks without an enabled field as enabled by default.
• For each remaining hook, do not attempt to interpret or evaluate hook condition expressions:
  • If the hook has no condition field, or it is null/empty, treat the hook as executable
  • If the hook defines a non-empty condition, skip the hook and leave condition evaluation to the HookExecutor implementation
• For each executable hook, output the following based on its optional flag:
  • Optional hook (optional: true):

    ## Extension Hooks
    
    **Optional Pre-Hook**: {extension}
    Command: `/{command}`
    Description: {description}
    
    Prompt: {prompt}
    To execute: `/{command}`
    

  • Mandatory hook (optional: false):

    ## Extension Hooks
    
    **Automatic Pre-Hook**: {extension}
    Executing: `/{command}`
    EXECUTE_COMMAND: {command}
    
    Wait for the result of the hook command before proceeding to the Goal.
    

• If no hooks are registered or .specify/extensions.yml does not exist, skip silently

Goal

Act as the ultimate Validation Gate before execution. Identify inconsistencies, duplications, ambiguities, and underspecified items across core artifacts (spec.md, plan.md) and Open Beads. Perform rigorous Reality Check, Feasibility Verification, and Bead Graph Health analysis using bv tools, ensuring the work shape is approved and testable.

Operating Constraints

STRICTLY READ-ONLY: Do not modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).

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 beads—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 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
• BEADS = Load open beads using br list --status=open --json
• GRAPH METRICS = Run bv --robot-insights and bv --robot-suggest

Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command). 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 Open Beads (br and bv):

• Bead IDs and Status
• Titles, Descriptions, and Exit States
• Priorities and Dependencies (Blockers/Unblocks)
• Graph Insights (cycles, priority mismatches, staleness)
• 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
• Bead coverage mapping: Map each bead 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
• Beads 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 beads
• Beads with no mapped requirement/story
• Success Criteria requiring buildable work (performance, security, availability) not reflected in beads

F. Inconsistency

• Terminology drift (same concept named differently across files)
• Data entities referenced in plan but absent in spec (or vice versa)
• Bead ordering contradictions or missing dependencies (e.g., integration beads not depending on foundational setup beads)
• Conflicting requirements (e.g., one requires Next.js while other specifies Vue)

G. Reality & Feasibility Gate (Validation)

• Mode/Repo Fit: Verify assumptions against actual repo files, APIs, commands, versions, and runtime constraints. Fail if the plan assumes nonexistent code, unsupported commands, stale versions, missing credentials, or unreachable services.
• Feasibility Evidence: Ensure evidence is concrete (existing code, API inspection, command output, test result). Fail if evidence is only "this should work", "likely", or based on LLM assumptions.
• Integration Readiness: Ensure proven parts can stitch together without hidden architecture work.
• Spike Rules: Unproven assumptions must be tested via Phase 0 (Spike) beads (One spike = one yes/no question). Spike code must not silently become production implementation.

H. Graph & Bead Health (Bead Review)

• Cold Pickup Test: Stress-test whether current open beads can be picked up cold by a worker.
• CRITICAL Bead Issues: assumed context, vague acceptance criteria, scope overload, unproven feasibility, or broken verification (unreachable exit).
• MINOR Bead Issues: missing rationale, implicit file assumption, fuzzy boundary, or known tradeoff not recorded.
• Graph Hygiene:
  • Check bv --robot-insights for cyclic dependencies (Cycles must be fixed).
  • Check bv --robot-suggest for duplicates, missing deps.
  • Check bv --robot-priority for priority misalignment.

I. Red Flags & Pressure Scenarios

• Skipping reality or feasibility gates.
• Accepting plausibility without concrete proof.
• Continuing after a NO spike result (should return to planning).
• Current story has vague proof or unobservable exit.
• Beads are not strictly tied to current story/work.
• Small fix creates epic/phase ceremony, or tough feature lacks epic map or equivalent capability/risk shape.

5. Severity Assignment

Use this heuristic to prioritize findings:

• CRITICAL: Violates constitution MUST, missing core spec artifact, circular dependency in beads (cycles), unproven feasibility for core architecture, bead lacks observable exit, or requirement with zero coverage that blocks baseline functionality.
• HIGH: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable exit state in beads, unproven blocking assumption without a spike, assumed context/scope overload in beads.
• MEDIUM: Terminology drift, missing non-functional bead coverage, priority misalignment in graph, missing rationale.
• LOW: Style/wording improvements, minor hygiene suggestions from bv.

6. Produce Compact Analysis Report

Output a Markdown report (no file writes) with the following structure:

Specification & Validation Report

1. Reality Gate

Mode Fit: PASS/FAIL | Repo Fit: PASS/FAIL | Assumptions: PASS/FAIL | Smaller Path: PASS/FAIL | Proof Surface: PASS/FAIL Decision: Proceed | Revise Planning | Run Spike First | Collapse Mode Evidence: [Concrete file/command/runtime evidence. Fail if evidence is only "this should work", "likely", or model knowledge.]

2. Feasibility Matrix

(Required if assumptions remain or high-risk feature. Decisions: READY, READY WITH CONSTRAINTS, NOT READY - RUN SPIKE, NOT READY - RETURN TO PLANNING)

Part / Assumption	Risk	Proof Required	Evidence	Result

3. Specification Consistency

ID	Category	Severity	Location(s)	Summary	Recommendation
A1	Duplication	HIGH	spec.md:L120-134	Two similar requirements ...	Merge phrasing; keep clearer version
(Generate stable IDs. Limit to top findings).

4. Bead Review Report

Beads reviewed:

• CRITICAL FLAGS (BR-): [assumed context, vague acceptance, scope overload, unproven feasibility, broken verification]
• MINOR FLAGS (BR-): [missing rationale, implicit file assumption, fuzzy boundary]
• CLEAN BEADS: BR-, BR-
• GRAPH & HYGIENE:
  • Cycles Detected: [Yes/No via bv --robot-insights]
  • Misaligned Priorities: [Yes/No via bv --robot-priority]

5. Coverage & Metrics

• Total Requirements: [N]
• Total Open Beads: [N]
• Coverage %: [N%]
• Critical Issues Count: [N]
• Unmapped Beads: [List or None]
• Constitution Alignment Issues: [List or None]

7. Provide Next Actions

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

• If CRITICAL issues exist or Feasibility is NOT READY: Recommend resolving before /speckit.implement (e.g., returning to planning, running spikes, fixing circular dependencies via br dep remove).
• If only LOW/MEDIUM and Feasibility is READY: User may proceed, but provide improvement suggestions.
• Provide explicit command suggestions: e.g., "Run /speckit.specify with refinement", "Run /speckit.plan to adjust architecture", "Run br update or br dep add to correct bead dependencies and scopes".
• Ask the user for Approval: "Approve execution for this work? (yes/no)"

8. Offer Remediation

Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)

9. Check for extension hooks

After reporting, check if .specify/extensions.yml exists in the project root.

• If it exists, read it and look for entries under the hooks.after_analyze key
• If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
• Filter out hooks where enabled is explicitly false. Treat hooks without an enabled field as enabled by default.
• For each remaining hook, do not attempt to interpret or evaluate hook condition expressions:
  • If the hook has no condition field, or it is null/empty, treat the hook as executable
  • If the hook defines a non-empty condition, skip the hook and leave condition evaluation to the HookExecutor implementation
• For each executable hook, output the following based on its optional flag:
  • Optional hook (optional: true):

    ## Extension Hooks
    
    **Optional Hook**: {extension}
    Command: `/{command}`
    Description: {description}
    
    Prompt: {prompt}
    To execute: `/{command}`
    

  • Mandatory hook (optional: false):

    ## Extension Hooks
    
    **Automatic Hook**: {extension}
    Executing: `/{command}`
    EXECUTE_COMMAND: {command}
    

• If no hooks are registered or .specify/extensions.yml does not exist, skip silently

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)

Context

$ARGUMENTS