/spec-workflow

name: spec-workflow
description: >
  Drive the spec-driven lifecycle for any non-trivial work item: SPIDR-split a
  new spec into vertical slices, transition state markers (DRAFT → READY_FOR_REVIEW
  → READY_FOR_IMPLEMENTATION → IN_PROGRESS → REVIEWED → RECONCILED → DONE; also
  DEFERRED for parked slices with a stated resolution trigger), enforce the
  reconciliation checklist before commit, and surface stale specs/ADRs whose
  `last_verified` date has aged past dependency changes. Use when starting
  non-trivial new work, creating a spec, transitioning a slice's state,
  parking a slice as DEFERRED, reconciling a reviewed slice, or auditing
  doc freshness. Do not use for quick one-off fixes that don't need a spec,
  or for bug-shaped work where `jig:bug-fix` is the better fit.
user-invocable: true

> **Working posture ([ADR-0056](../../docs/decisions/adr-0056-adversarial-register-quarantine.md)).** > Adversarial review is a *named, bounded operation.* This workflow invokes > review passes (frame-critique / craft), whose skeptical register belongs > *inside* those isolated reviewer subagents. Outside a review, default to > collaborative and solution-forward; don't carry the adversarial stance into > ordinary conversation.

> Spec 003 promoted this skill from stub to active. The deterministic state > mutations live in `workflow.py`; this SKILL.md drives the judgment layer.

What this skill does

• Guides SPIDR-splitting a new spec into vertical slices (Spike last, not first —

try Rules / Data / Interface / Path first).

• Flags slices that look like horizontal phasing (no user-facing layer touched).
• Drives the spec lifecycle state transitions via `workflow.py`.
• Coordinates implementer + reviewer subagent invocations at the right points.
• Enforces the reconciliation checklist before a slice goes DONE.
• Consults `docs/memory/glossary.md` when drafting ACs to surface unknown domain terms.
• Surfaces skill-routing observability via `workflow.py routing-stats [--days N]` —

a read-only histogram of which skills fired (jig baseline vs. richer/"other" skill per category) from `.claude/skill-usage.jsonl` (slice 041-02).

• Surfaces use-case coverage via `workflow.py coverage [--project-dir DIR]` — a

read-only, **advisory** (non-blocking), project-wide **bidirectional** check (slice 068-03): a deterministic set-difference over the `use_cases:` trace links that reports use cases with no implementing spec (coverage gap) and specs citing no parent use case (scope creep). No-op when the project has no `## Use cases` section.

• Guards the status board via `workflow.py check-board <project-dir>` — a

read-only audit that exits non-zero when `docs/specs/README.md` no longer matches the spec records, or when two spec directories claim one number. Writes nothing, so it is safe to run in CI against a checkout.

• Surfaces gate-bypass telemetry via `workflow.py gate-stats [--days N]` — a

read-only per-gate histogram of how often each gate honored its env-var override (an override-frequency audit trail, not a gate-value verdict) from `.claude/skill-usage.jsonl` (slice 078-02).

SPIDR splitting

All non-trivial specs are SPIDR-split into vertical slices before implementation begins. **Spike is the last resort — try Path / Interface / Data / Rules first.**

• **S — Spike**: research/learning activity. Only when none of P/I/D/R

apply. AI agents default to spiking too eagerly — resist.

• **P — Path**: split by alternative paths through the story (happy

path first, edge paths later).

• **I — Interface**: split by UI / platform / channel (minimal first,

polish later).

• **D — Data**: split by data subset or format (less data first).
• **R — Rules**: split by business rules (simple first, edge cases later).

**Anti-horizontal-phasing rule:** every slice must touch the user-facing layer and deliver end-to-end value. A slice that touches only the DB or only the parser is horizontal phasing — re-split.

See [`worked-example-spidr-split.md`](worked-example-spidr-split.md) for one applied example per axis plus a jig-native dogfood case (spec 017's three-axis split). The canonical primer for all five axes lives at [`docs/spec-workflow/spidr-primer.md`](../../docs/spec-workflow/spidr-primer.md).

Spike slices

When SPIDR's S axis fires during decomposition (none of P / I / D / R apply because the team doesn't yet know enough to pick), the resulting slice is marked `kind: spike` in its frontmatter — the typed enum that `spec_lint.py` validates.

**When to introduce a spike during decomposition.** Reach for S only after trying R / D / I / P. The bias to resist is "let me research this first" as a prelude to "now let me build it as one big slab" — that is horizontal phasing in a trench coat. If the spike would conclude with "now ship the implementation," the implementation IS the slice, and the research goes inside it.

**Body shape (four labelled blocks).** A `kind: spike` slice carries four blocks alongside the standard Goal / DoR / AC / DoD scaffolding. **Each label must be written with the trailing colon (`**Question:**`, etc.) — that is what `spec_lint.py` matches against.**

• **Question:** — one sentence stating the open question. Set at DRAFT.
• **Time-box:** — explicit budget (e.g., "1 day", "4 hours"). Set at DRAFT.
• **Findings:** — bullet evidence collected during the spike. Filled

during IN_PROGRESS.

• **Outcome:** — one of `ADR-NNNN created` / `spec NNN-NN unblocked` /

`abandoned (reason)`. Multiple outcomes separated by `;` (e.g., `ADR-0007 created; spec 030-02 unblocked`). Set at DONE.

`spec_lint.py` soft-warns when a `kind: spike` slice is missing any of the four labels — mid-flight spikes legitimately have empty Findings / Outcome, so this is a warning, not a hard error.

**Always nested, never standalone.** Spike slices live inside a real spec — never as a standalone `docs/spikes/` artifact. The 1-slice-spec case (no clear downstream spec yet, ju