spec-workflow

Files (4)

• SKILL.md
• worked-example-behavioral-verification.md
• worked-example-spidr-split.md
• workflow.py

SKILL.md (first lines)

> **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.
- Surfaces use-case progress via `workflow.py progress [--summary] [--project-dir DIR]` — a
  read-only, **advisory** rollup (slice 116-01, [ADR-0064](../../docs/decisions/adr-0064-use-case-progress-rollup-in-jig.md)):
  per use case, the specs citing it with their status and done/known slice
  **counts** (never percentages), then an **Unanchored** bucket for specs citing
  no resolvable use case. Derived on every run, stores nothing; a progress view,
  not a drift check. `--summary` prints the compact view `/jig:orient` copies
  (totals, use cases with no done slice or no spec, Unanchored specs; slice
  116-02). No-op when the project has no `## Use cases` section or its marker
  says `status: unfilled` / `skipped` (not elicited yet).
- Retires the seeded genesis spec via `workflow.py retire-genesis [--project-dir DIR] [--dry-run]`
  (slice 121-02, [ADR-0067](../../docs/decisions/adr-0067-genesis-spec-zero.md)).
  It removes `000-adopt-jig/` (new shape) or, in the legacy shape, `001-adopt-jig/`
  (either one only when its frontmatter has `skill: scaffold-init`; otherwise reported
  "not recognised as the jig seed; left in place") plus the legacy `first-spec` stub dir only while it is an untouched
  stub (only `spec.md`, still `DRAFT`, with the seed's heading, lead, slice
  heading and `_TODO_` placeholder intact; otherwise kept and reported). It
  deletes the primer / `adoption-readiness.md` list items that point at the
  removed spec, backticks any other link in `CLAUDE.md`, `AGENTS.md`,
  `adoption-readiness.md` and a kept stub, and regenerates the board. Links
  from your own files are **reported, never rewritten**. It **refuses**
  (non-zero, nothing written) when no other spec exists, since a re-scaffold
  would re-seed the genesis. `--dry-run` prints the plan and writes nothing.
  When the first non-genesis spec rolls up to `DONE`, `transition` prints a
  one-line hint naming this command (stderr, non-blocking, once).
- 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, just an

From ramboz/jig, MIT.

More from ramboz/jig