/ratchet-backlog

name: ratchet-backlog
description: Create, validate, extend, groom, and migrate ratchet BACKLOG.md files — from TODO/FIXME comments, GitHub issues, a PRD/notes file, or plain conversation. Enforces the ratchet:v1 and ratchet:v2 contracts, especially the core invariant "no acceptance criteria, no item"; v2 adds parallel lanes (per-lane state files) for multi-agent execution. Use when the user says "make a backlog", "ratchet backlog", "validate the backlog", "add an item", "migrate the backlog to v2", or "turn these issues/TODOs into a backlog".

Ratchet Backlog — the curator

The backlog file is the contract between whoever defines work and whoever (or whatever) executes it. Your job is to make that contract sharp: every item small enough for one commit, specific enough for a smaller model, and checkable enough that "done" is an observation, not an opinion.

Format authority: `docs/backlog-format.md` in the ratchet repo (github.com/afrizzal/ratchet); `examples/BACKLOG.example.md` there is a full worked example. Neither ships with an installed skill, so the compact contract is embedded here:

# BACKLOG — <scope>
<!-- ratchet:v1 -->                      ← version marker, required

## Global checks                         ← optional; each line one backticked command
- `npx tsc --noEmit`

## Items                                 ← one ### block per item, one commit each

### SEC-01 — <title> [P0]                ← ID matches [A-Z]+-\d+, unique; priority [P0..P3]
- Tags: —                                ← only canonical gates: [RISKY] [OPS] [USER-DECISION] [BASELINE], or —
- Depends: —                             ← comma-separated IDs, all must be done first
- Evidence: path:line — <verified observation>
- Spec: <the exact minimal change — executors implement this and nothing more>
- Acceptance:                            ← ≥1; runnable commands or observable behaviors
  - [ ] `<command>` <expected result>

## Ledger                                ← one row per item; statuses: todo/in-progress/done/blocked/needs-human/skipped
| ID | Status | Attempts | Commit | Note |
|---|---|---|---|---|
| SEC-01 | todo | 0 | — | — |

## Journal                               ← append-only; - <date> <ID> <what happened>

**Format v2 — parallel lanes** (marker exactly `<!-- ratchet:v2 -->`; full spec: `docs/backlog-format.md` §5 in the ratchet repo). The backlog holds `## Global checks` + `## Lanes` + `## Items` and **no Ledger/Journal**; each lane's state lives in `lanes/<lane>.md`, single writer, so parallel executors never write the same file:

## Lanes                                 ← required in v2; first lane's Scope is the literal (rest) = the default lane
| Lane | Scope | Notes |
|---|---|---|
| core | (rest) | default lane — shared/cross-cutting work; barrier runs only |
| api | `src/api/**`, `prisma/**` | server hardening |

### SEC-01 — <title> [P0]                ← items gain one required field:
- Lane: api                              ← before Tags:; must name a declared lane
...

# LANE api — <scope>                     ← lanes/api.md; created by YOU, never by the loop
<!-- ratchet:v2:lane api -->             ← marker must match filename + declaration

## Ledger                                ← exactly this lane's items' rows, in Items order
| ID | Status | Attempts | Commit | Note |
|---|---|---|---|---|
| SEC-01 | todo | 0 | — | — |

## Journal                               ← append-only; also carries run markers:
                                         ← - <date> run started (lane api, branch ratchet/api) / run ended (lane api)

Lane names match `[a-z][a-z0-9-]*`; named-lane scopes are disjoint backticked globs. An item's row and its lane file materialize together with the item — **you** create lane files; the loop refuses a declared lane whose file is missing.

**Human write windows (v2).** You (and the human you act for) write the backlog or a lane file only on the integration branch, and only while the affected lane is *closed* — its journal's last run marker is `run ended`, and no `ratchet/<lane>` branch sits unmerged ahead of the integration branch. While any lane run is open, the backlog is frozen (a Spec edited under a live run can merge cleanly next to a `done` row earned against the old Spec). If asked to edit anyway, refuse and name the open lane.

Default file location: `ratchet/BACKLOG.md`.

Modes

`create from <source>`

Build a new backlog (or extend an existing one — never clobber Ledger history; new items get new IDs).

• **`todos`** — scan the codebase for `TODO|FIXME|HACK|XXX` markers. Each marker: read the surrounding code to reconstruct intent; markers too vague to spec go into a "needs definition" note for the user, not into items.
• **`github issues`** — `gh issue list --state open --json number,title,body,labels` (confirm `gh` works first). Map issue → item; keep `(#123)` in the title for traceability. Issues that are epics → split or park as needs-definition.
• **`<file>`** (PRD, meeting notes, audit report) — read it; extract discrete, committable units of work.
• **conversation** — interview the user briefly: what, where (files if known), how they'd verify it. Push back on vagueness once, then park it.

For every candidate item you MUST establish, in this order: 1. **Evidence/context** — a real `file:line` where the work anchors (open the file; verify). If no code anchor exists (new feature), anchor to the closest integration point. 2. **Spec** — the minimal change, one commit's worth. Bigger → split with `Depends:`. 3. **Acceptance** — ≥1 runnable command or observable behavior. If neither you nor the user can define one, the item does not enter the backlog; it enters a "## Needs definition" note at the bottom of your report. 4. **Tags** — `[USER-DECISION]` for product judgment, `[OPS]` for infra/credentials, `[RISKY]` for destructive/irreversible. When in doubt on destructive things, tag — the loop can