spec-kit-analyze

name	spec-kit-analyze
description	Use when `spec.md`, `plan.md`, and `tasks.md` exist and you need a read-only Spec Kit audit for consistency, requirement-to-task coverage, ambiguity, duplication, or constitution conflicts before implementation.

Spec Kit Analyze

Run a non-destructive cross-artifact quality audit before implementation.

Invocation Notice

• Inform the user when this skill is being invoked by name: spec-kit-analyze.

When to Use

• tasks.md exists and you want a pre-implementation consistency check across spec/plan/tasks.
• You suspect coverage gaps, requirement drift, ambiguous language, or contradictory artifacts.
• You need a constitution-alignment gate without editing artifacts yet.

When Not to Use

• Any prerequisite artifact is missing (spec-kit-specify, spec-kit-plan, or spec-kit-tasks first).
• You need targeted remediation edits now (spec-kit-reconcile).
• You are executing implementation work (spec-kit-implement).

Router Fit

• Primary route from spec-kit after spec-kit-tasks.
• Read-only quality gate before spec-kit-implement.
• Default handoff to spec-kit-reconcile when findings require coordinated artifact updates.

Critical Constraints

• Strictly read-only: do not modify files.
• Treat memory/constitution.md as authoritative; any MUST-level conflict is CRITICAL.

Preconditions

• Run from repository root (or a subdirectory inside it).
• Active feature context resolves to one feature directory with spec.md, plan.md, and tasks.md.

Workflow

1. Resolve artifact paths and enforce prerequisite gate:

   • Run scripts/check-prerequisites.sh --json --require-tasks --include-tasks exactly once.
   • Parse:
     • FEATURE_DIR
     • AVAILABLE_DOCS
   • Derive:
     • SPEC = FEATURE_DIR/spec.md
     • PLAN = FEATURE_DIR/plan.md
     • TASKS = FEATURE_DIR/tasks.md
   • If any required artifact is missing, stop and route to the owning sibling skill.

2. Load focused sections from:

   • spec.md: requirements, stories, acceptance criteria, edge cases.
   • plan.md: architecture/stack decisions, phases, constraints.
   • tasks.md: task IDs, phase grouping, [P] markers, referenced paths.
   • memory/constitution.md: principle names and normative MUST/SHOULD statements.

3. Build internal maps:

   • Requirement inventory (functional + non-functional) with stable keys.
   • Story/action inventory with acceptance-test intent.
   • Task-to-requirement/story coverage mapping.
   • Constitution obligations relevant to spec/plan/tasks scope.

4. Detect and classify issues:

   • Duplication: overlapping or near-duplicate requirements.
   • Ambiguity/placeholders: vague quality terms, TODO/TKTK/placeholder tokens.
   • Underspecification: requirements lacking measurable outcomes or clear objects.
   • Constitution conflicts: violations against MUST principles (CRITICAL).
   • Coverage gaps: requirements without tasks and tasks without mapped requirement/story.
   • Cross-artifact inconsistency: terminology drift, entity mismatch, ordering contradictions.
   • Cap findings at 50 rows; summarize overflow counts by category.

5. Assign severity and output a compact report with stable IDs, coverage table, and metrics.

   • CRITICAL: constitution MUST violations, missing core coverage that blocks baseline behavior.
   • HIGH: conflicting/duplicate requirements, untestable or high-risk ambiguity.
   • MEDIUM: terminology drift, non-functional coverage gaps, underspecified edge cases.
   • LOW: wording/style cleanup without execution impact.

6. Recommend next actions:

   • If CRITICAL/HIGH findings require cross-artifact edits, block spec-kit-implement and route to spec-kit-reconcile with a concise gap summary.
   • If only one artifact needs focused updates, route to its owner skill (spec-kit-specify, spec-kit-plan, or spec-kit-tasks).
   • Otherwise provide prioritized improvements and whether implementation can proceed.

7. Offer follow-up only:

   • Ask whether to run spec-kit-reconcile using top findings as the gap report.
   • Do not apply any edits in this skill.

Output

• Markdown report only (no file writes) containing:
  • Findings table: ID | Category | Severity | Location(s) | Summary | Recommendation
  • Requirement coverage table: Requirement Key | Has Task? | Task IDs | Notes
  • Constitution alignment issues (if any)
  • Unmapped tasks (if any)
  • Metrics:
    • Total requirements
    • Total tasks
    • Coverage percentage
    • Ambiguity count
    • Duplication count
    • Critical issues count
  • Next-step routing recommendation

References

• references/command-analyze.md
• scripts/check-prerequisites.sh
• https://github.com/github/spec-kit/blob/9111699cd27879e3e6301651a03e502ecb6dd65d/templates/commands/analyze.md