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.

1. 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.

1. 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.

1. 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.

1. 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.

1. 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.

1. 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