/ratchet-recommend

name: ratchet-recommend
description: Turn a ratchet BACKLOG.md + Ledger into a prioritized, model-routed execution plan (ratchet/NEXT.md) — what to do next, who should do each item (an autonomous cheap model, a supervised cheap model, a senior model, or a human decision), in what order, and with what verification. Read-only. Changes no code, no items, no ledger. Use after /ratchet-audit, after a /ratchet-loop run, or when the user asks "what should I do next?" about a project that has a ratchet backlog.

Ratchet Recommend — the navigator

Your output is a **route, not a report card**. The ledger already says *what state each item is in*; a report just re-states it. Your job is to say *what to do next, who should do it, and in what order* — so that a human, or a cheaper model, can act on the backlog without re-deriving the senior judgment that produced it. That routing **is** the thing that lets a small model land a fix as safely as an expensive one: it inherits the decision instead of guessing it.

Invocation

/ratchet-recommend [path]

• `path` — backlog file. Default `ratchet/BACKLOG.md`. **Read-only.**

What it reads / writes

• **Reads:** the Items (Tags, priority, Spec, Acceptance, `Depends:`), the Ledger (status per item), the Journal. On a v2 backlog that means the backlog **plus every `lanes/<lane>.md`** — ledgers and journals both.
• **Writes:** only `NEXT.md`, alongside the backlog file (default `ratchet/NEXT.md`). It changes no source, no item, no ledger row, no tag. It recommends; the loop executes and humans decide. On a v2 backlog, NEXT.md is written **on the integration branch only** — never in a lane worktree (lane branches carrying their own copies is a guaranteed merge conflict).

Phase 1 — Snapshot

Count all six ledger states (`done` / `todo` / `in-progress` / `needs-human` / `blocked` / `skipped`) — on a v2 backlog, across every lane file, and report the counts per lane as well as in total. An `in-progress` row with no run in flight is debris from a crashed session — the loop's preflight resets it to `todo` automatically, so route it as `todo` and note the crash. **v2 exception: an `in-progress` row in an *open* lane** (the lane journal's last run marker is `run started`, not `run ended`) **may be a live session, not debris.** Do not route it as `todo`, do not suggest re-launching it; flag the lane as open and say the item belongs to whoever is running it. Check the baseline: if a `[BASELINE]` item is not `done`, **nothing else matters** until it is — say so first (v2: name its lane, since every other lane is blocked until that lane merges).

Phase 2 — Assign every open item a route

(A **route** is the who-runs-it category below — BASELINE / DECIDE-FIRST / OPS / RISKY-REVIEW / SENIOR / SUPERVISED / AUTONOMOUS. Earlier versions called routes "lanes"; that word now means a v2 backlog's parallel partitions, which are a different axis — an item has both a lane and a route.)

Route every item whose status is **not** `done` or `skipped` — that includes `needs-human` and `blocked`; their route says what releases them. The mapping is mechanical — derived only from the item's Tags, status, `Depends:`, and the literal text of its Spec/Evidence/Acceptance — so a cheaper model reaches the same routing a senior would. Two defined terms, both checkable from the file:

• **Sensitive** — the Spec or Evidence mentions any of the trigger list (verbatim from executor rule 1): **auth/permissions, tenant boundaries (companyId / ownership scoping), payments or money math, GL/journal posting, database migrations, secrets/env, file or row deletion, or session/cookie handling**.
• **Small** — the Spec names at most 2 files and no migration. When unsure, it is **not** small.

Routing order:

1. **Status overrides first.** `blocked` and `needs-human` items are governed by the status bullets below the table — those bullets pick the route (sometimes by delegating back to the table) **and add the mandatory human release edits**. Only `todo` items (and crash-debris `in-progress`, treated as `todo`) enter the table directly. 2. **Then the table, top-down; first match wins.**

| Route | Match | Who runs it | Verify | |---|---|---|---| | **BASELINE** | `[BASELINE]` and its Ledger row is not `done` (redness is judged from the Ledger, never by running commands). A human-gate tag **wins over** `[BASELINE]` — such an item routes to its gate row, flagged "baseline-blocking — unpark first" | anyone, **first** — and on a v2 backlog, **everything else waits**: a red baseline blocks every lane until this item's lane runs it, merges, and the others refresh from the integration branch. If the item is *sensitive*, its invocation must carry `--only <ID> --verify fresh` (the loop exempts `[BASELINE]` from the `--only` requirement, but prescribe it anyway) | its own AC (fresh if sensitive) | | **DECIDE-FIRST** | `[USER-DECISION]`, **or** every Acceptance criterion is manual/infra with no runnable command | a human answers the question / defines a runnable criterion; then unpark and re-route | — | | **OPS** | `[OPS]` | human/ops (needs infra/credentials/a plan choice) | — | | **RISKY-REVIEW** | `[RISKY]` (migration or not) | a human reviews the Spec — for migrations: the SQL plus a backup/shadow-db plan — then **unparks it** (removes the tag, journals the approval, status → `todo`, per the format's Human transitions); once unparked it re-routes through the rows below | per re-route — but the **first run after a `[RISKY]` unpark always carries `--verify fresh`**, whatever row it lands in | | **SENIOR** | sensitive **and** not small | strong model **+ `--verify fresh`**, invoked with explicit `--only`; never a cheap model solo | fresh | | **SUPERVISED** | sensitive **and** small | cheap model **allowed, with `--verify fresh`** and explicit `--only` | fresh | | **AUTONOMOUS** | not sensitive **and** every AC is a runnable backticked command or an observable the executor can check from outp