@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/backlog/SKILL.md

@@ -1,54 +1,77 @@
 ---
 name: backlog
-description: "The engineering backlog registry for deferred-but-approved work: each deferred job lands here with its spec, origin and unblock condition. Use when the user says 'defer it', 'add it to the list', 'later' or 'not now', asks what is on the backlog, says 'pick up {id}', or completes an item. BACKLOG.md is the registry; entries move deferred, ready, in-progress, done, and a re-audit deletes rotted ones."
+description: "Registry and routine for approved but postponed engineering work: each item keeps its full spec, origin and unblock condition, and moves through deferred, ready, in-progress and done. Use when the user postpones work ('later', 'not now', 'put it on the list', 'backlog this'), asks what is on the backlog or still owed, works the backlog, picks up an item by id or the next one, finishes an item, or when a rename, a deleted subject or a doubted claim calls for a re-audit. Not for Jira or GitHub tickets, and never for summarising or rewriting a deferred spec."
 user-invocable: true
 argument-hint: [list | add | pick <id> | done <id> | re-audit]
 allowed-tools: Read, Grep, Glob, Edit, Write
 metadata:
   version: 1.0.0
+  source: multi-agent-pipeline
 ---
 
-# backlog - deferred work, kept whole
+# backlog - postponed work without context loss
 
-> **Layer:** workflow - the deterministic registry routine for deferred jobs.
-> **Bundled:** [BACKLOG.md](BACKLOG.md) - the registry. The heart of this skill.
-> **Iron rule:** moving a job onto this list is a MOVE, never a rewrite - the FULL spec
-> travels verbatim. A compressed one-liner is a loss; the point of the backlog is that
-> deferring costs nothing later. The registry stays honest in the other direction too:
-> entries are re-audited against live code, and an entry whose named types or premises
-> no longer exist is DELETED, never left readable as live.
+> **Layer:** workflow in practice: a fixed routine over one registry file.
+> **Registry:** [BACKLOG.md](BACKLOG.md), bundled with this skill. Every operation below reads or edits it.
 
-## When to load
+## Why it exists
+Work that gets postponed as a single line tends to die there. By the time someone returns to it, the reasoning, the constraints and the edge cases are gone, and the job is either re-derived from scratch or quietly dropped. This registry pays the cost of "later" once, at the moment of deferral, by storing the job exactly as it was understood then.
 
-- The user defers work: "defer it", "add it to the list", "later", "not now", "backlog this".
-- The user asks about it: "what's on the backlog", "what's on the list", "what's owed".
-- The user works it: "work the backlog", "pick up <id>", "do the next one".
-- An item completes: mark it done, and retire the record once what it taught has a home.
-- A staleness signal arrives (a rename, a deleted subject, a doubted claim): re-audit.
+## Two rules
+1. **Deferral moves the spec; it does not edit it.** The full description goes into the entry word for word. Shortening it to one line is data loss, even when the line reads well.
+2. **The registry must stay true.** Entries are checked against the live code. One whose named types, files or premises have disappeared is deleted, not kept around looking actionable.
 
-## The registry contract
+## Entry fields
+| Field | Content |
+|---|---|
+| `id` | short, stable kebab-case slug, assigned when the entry is added and never changed |
+| `title` | one line |
+| `state` | `deferred`, `ready`, `in-progress` or `done` |
+| `origin` | the task, PR, review finding or conversation that produced the job |
+| `spec` | the complete description, verbatim, as a block literal; never a summary |
+| `unblock` | the dependency, decision or date that makes it actionable |
+
+The file layout (sections Ready, Deferred, In progress, Done, and the entry template) is fixed in `BACKLOG.md`: each item is a heading with its id and title, followed by bullets for state, origin, unblock and spec.
 
-Every entry in `BACKLOG.md` carries, verbatim:
+## State machine
+`deferred` -> `ready` -> `in-progress` -> `done`. States only move forward.
 
-- **id** - short stable slug (`kebab-case`), assigned on add.
-- **title** - one line.
-- **state** - `deferred` -> `ready` -> `in-progress` -> `done`. Entries move forward; they leave the registry only by the two rules below (rot, or a re-homed done record), never by being quietly rewritten.
-- **origin** - where it came from (the task/PR/finding/conversation that spawned it).
-- **spec** - the FULL description, verbatim from when it was deferred. Not a summary.
-- **unblock** - the condition that makes it actionable (a dependency, a decision, a date). `deferred` items without an unblock condition are just `ready`.
+An entry marked `deferred` with no unblock condition is not waiting for anything, so it is `ready`.
 
-Prefer an append-only markdown table or section list in `BACKLOG.md`; never overwrite an entry's spec on a state change - only its `state` line moves.
+Storage is append-only in spirit: when the state changes, only the state line (and the section the entry sits under) changes. The spec is never overwritten.
 
 ## Operations
 
-| Command | Action |
-|---|---|
-| `list` | Show entries grouped by state (ready first, then deferred, then in-progress; done collapsed). |
-| `add` | Capture the deferred job with its full spec + origin + unblock condition. Assign an id. |
-| `pick <id>` | Move `ready`/`deferred` -> `in-progress`; surface the full spec so work resumes with zero context loss. |
-| `done <id>` | Move -> `done` with the evidence (PR/commit + date). The record RETIRES from the registry once what it taught is written into the skill or doc that owns it - git history is the archive of what was owed and delivered. A done entry kept past that point is a second place for the same truth to rot. |
-| `re-audit` | Verify every entry's named types, paths and claims against LIVE code (binary-safe: `LC_ALL=C grep -a`, so a repo with binary blobs does not silently return nothing). A subject that no longer exists deletes its entry; a changed fact restates it. **Numbers move by measurement, never by edit** - a count adjusted to match an impression reads as evidence and is worse than no count. |
+### `list`
+Group entries by state in the order ready, deferred, in-progress. Show done entries collapsed, as a count or a one-line list of ids.
+
+### `add`
+Take the complete spec as it stands, the origin and the unblock condition. Derive an id. Write the entry under the section that matches its state (`ready` when nothing blocks it).
+
+### `pick <id>`
+Find the entry, which must be `ready` or `deferred`. Change its state to `in-progress`, move it to that section, and print the full spec so the work can resume with nothing to reconstruct.
+
+### `done <id>`
+Set the state to `done` and record the evidence: the PR or commit, and the date. The record is temporary. Once the lesson it carries has been written into the skill or document that owns that area, delete the entry: git history keeps the original, and a done entry left in place becomes a second copy of the truth that drifts from the real one.
+
+### `re-audit`
+For each entry, check every type, path and factual claim it names against the live repository. Use a binary-safe search so repos that contain binary blobs do not make grep silently skip files:
+
+```bash
+LC_ALL=C grep -rIa --line-number '<TypeOrPath>' .
+```
+
+(`LC_ALL=C` avoids locale decoding failures; `-a` treats every file as text.) Then:
+- subject gone: delete the entry;
+- a fact changed: restate that fact in the entry;
+- a number in the entry: measure it again and write the measured value.
+
+## Leaving the registry
+An entry is removed for exactly two reasons: its subject rotted away (found by re-audit), or it is done and its lesson now lives in the owning skill or doc. Nothing leaves by being rewritten until it no longer says what it said.
 
-## Why keep it whole
+## Numbers
+A count in an entry changes only when it is measured again. Editing a number to match an impression makes it look like evidence when it is not.
 
-The failure mode this skill prevents: an agent defers a job with a one-line note, the surrounding context evaporates, and picking it up later means re-deriving the spec (or silently dropping it). Storing the full spec at defer-time makes deferral safe - the cost of "later" is paid once, up front, not lost.
+## Not for
+- Work items that belong in the team's issue tracker (Jira, GitHub issues): file them there.
+- Condensing, paraphrasing or "cleaning up" a deferred spec.