# Speckit Analyze

> Spec-Kit: Analyze

- Skill: `jorelcb/speckit-analyze` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jorelcb/speckit-analyze`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jorelcb/speckit-analyze/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jorelcb (https://skillmd.com/u/jorelcb)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jorelcb/speckit-analyze

---

# Spec-Kit: Analyze

Run a non-destructive, **read-only** cross-artifact consistency and quality check across `spec.md`, `plan.md`, and `tasks.md` before implementation. This is the final quality gate. Invoked as `/speckit-analyze`.

**Lifecycle position** — step 5 of the chain:
[[speckit-specify]] → [[speckit-clarify]] → [[speckit-plan]] → [[speckit-tasks]] → `/speckit-analyze` → implement.

Runs only after [[speckit-tasks]] has produced a complete `tasks.md`. It validates the trio of artifacts and clears the path to implementation — it does **not** modify them.

## When to use

- All three artifacts exist (`spec.md`, `plan.md`, `tasks.md`).
- Immediately before starting implementation, to catch gaps, contradictions, and uncovered requirements.

## Operating constraints

- **Strictly read-only.** Never modify any file. Output a structured report and, optionally, a remediation plan the user must explicitly approve.
- **Constitution is authority.** Any conflict with a MUST principle in `.specify/memory/constitution.md` is automatically CRITICAL and resolved by fixing the spec/plan/tasks — never by diluting the principle.

## Flow

1. **Load artifacts** (minimal, progressive disclosure):
   - From `spec.md`: overview, Functional Requirements, Success Criteria, user stories, edge cases.
   - From `plan.md`: architecture/stack, data-model references, phases, technical constraints.
   - From `tasks.md`: task IDs, descriptions, phase grouping, `[P]` markers, referenced file paths.
   - From `.specify/memory/constitution.md`: principle names and MUST/SHOULD statements.
   - Abort if any required file is missing — tell the user which prerequisite command to run.
2. **Build semantic models** (internal, not echoed): requirements inventory keyed by `FR-###` / `SC-###`; user-story/action inventory; task→requirement coverage mapping; constitution rule set. Include only Success Criteria that require buildable work — exclude post-launch KPIs.
3. **Run detection passes** (high-signal; cap at 50 findings, summarize overflow):
   - **Duplication** — near-duplicate requirements; flag the weaker phrasing for consolidation.
   - **Ambiguity** — vague adjectives (fast, scalable, secure, robust) without measurable criteria; unresolved placeholders (TODO, ???, `<placeholder>`).
   - **Underspecification** — requirements missing object/measurable outcome; stories missing acceptance criteria; tasks referencing undefined components.
   - **Constitution alignment** — any element conflicting with a MUST principle, or a missing mandated gate.
   - **Coverage gaps** — requirements with zero tasks; tasks with no mapped requirement; buildable Success Criteria not reflected in tasks.
   - **Inconsistency** — terminology drift; entities in plan but absent from spec (or vice versa); task-ordering contradictions; directly conflicting requirements.
4. **Assign severity:** CRITICAL (constitution MUST violation, missing core artifact, zero-coverage requirement blocking baseline) · HIGH (conflicting/duplicate requirement, untestable security/performance attribute) · MEDIUM (terminology drift, missing non-functional coverage, underspecified edge case) · LOW (wording/redundancy not affecting execution).
5. **Emit a compact report** (see below).
6. **Offer remediation** — ask whether to suggest concrete edits for the top issues. Never apply them automatically.

## Report structure

- A findings table: `| ID | Category | Severity | Location(s) | Summary | Recommendation |` (one row per finding; stable IDs prefixed by category initial, e.g. `A1`, `D2`).
- A **Coverage Summary** table: `| Requirement Key | Has Task? | Task IDs | Notes |`.
- **Constitution Alignment Issues** and **Unmapped Tasks** sections (if any).
- **Metrics**: total requirements, total tasks, coverage % (requirements with ≥1 task), ambiguity count, duplication count, critical-issue count.
- **Next Actions**: if CRITICAL issues exist, recommend resolving before implement; otherwise the user may proceed. Suggest explicit follow-ups (re-run [[speckit-specify]] to refine, [[speckit-plan]] to adjust architecture, or hand-edit `tasks.md` to close a coverage gap).

## Quality criteria

- Deterministic — rerunning without changes yields consistent IDs and counts.
- High-signal — cite specific instances, not generic patterns; never hallucinate missing sections.
- Constitution violations always surface as CRITICAL.
- Zero-issue runs still emit a success report with coverage statistics.

## Don'ts

- Don't modify any file — this is read-only analysis.
- Don't apply remediation edits without explicit user approval.
- Don't dilute, reinterpret, or silently ignore a constitution principle.
- Don't hallucinate sections that are absent — report them as missing.
- Don't exceed 50 findings in the table; aggregate the rest in an overflow summary.

## Done when

- All three artifacts (plus constitution, if present) loaded and cross-analyzed.
- A structured report emitted with findings, coverage summary, metrics, and next actions.
- Remediation offered but not auto-applied; the user knows whether it's safe to implement.

## Going deeper

Previous: [[speckit-tasks]]. Next: implementation (execute `tasks.md` once this gate is clear). Full chain: [[speckit-specify]] · [[speckit-clarify]] · [[speckit-plan]] · [[speckit-tasks]].