/backlog

name: backlog
description: Read, work, and maintain a Git repo's deferred-work items in docs/backlog/, one file per item. Use when the user says "backlog", "check backlog", "what's on my backlog", "work the backlog", "address the backlog", "add to backlog", "clean up backlog", or when a review or task produced items that are real but not being fixed now. Owns the item format and the create-then-delete lifecycle.
allowed-tools: Read, Edit, Write, Bash, Grep, Glob, AskUserQuestion

Backlog

`docs/backlog/` at a repo root holds work that is real but not being done now: a defect a change did not introduce, drift with no user-visible symptom, a fix whose blast radius exceeded its value, an idea worth keeping. One file per item. It is the maintainer's own list — it never gates anything and never reaches a contributor.

The directory path is fixed, so every invocation in a repo reads and writes one predictable store.

**Git only.** The lifecycle is expressed in Git — `git rm` to close an item, branch detection before writing, staging and committing the file. Outside a Git repository, say so plainly and stop; do not improvise an equivalent in another VCS.

Item format

`docs/backlog/<slug>.md`. The slug names the defect, not the file it lives in (`reopen-fallback-ignores-frontmost.md`), so it can be cited from a commit and dedupe is a filename check.

---
worth: later
where: internal/window/library.go:537
added: 2026-08-05
---
# reopen fallback ignores the last-frontmost window

`reopen`'s fallback ignores which window was last frontmost once `frontmost` is nil, so a multi-window
user's last-window capture replays only when the exited window happened to be `windows.first`. Surfaced
reviewing PR #370; the fix touches restore ordering, which is why it was deferred rather than done inline.

Three frontmatter fields, written once and rewritten only as **Appending** below allows:

• **`worth: yes | no | later`** — the triage call, and the field the list is ordered by:
• **`yes`** — the value is agreed and it should be fixed. Says nothing about schedule: an item

blocked on an upstream release is still `yes` if nobody disputes it is worth doing.

• **`later`** — the value decision itself is unresolved, not the work. The body must name the unknown

or the condition that would settle it; without that it is a `yes` or a `no` in disguise.

• **`no`** — a decision not to fix, kept so the same finding is not rediscovered and re-argued by the

next review that touches the file. Keep a `no` only while that rationale still earns its place; once it does not, delete the file rather than carrying it.

• **`where: path:line`** — omit when the item is not anchored to one place. Its path narrows the dedupe

search alongside the slug and the line is a navigation hint that moves. Compare paths only when both items have `where`; two items missing it are not thereby the same item.

• **`added: YYYY-MM-DD`** — never updated, so it reads as age. A year-old item is itself information.

Zero-pad it so the values sort lexically.

The H1 is the title. The body below it has no required sections — repro, what was tried, the review that surfaced it, links, a snippet, in whatever shape suits. A two-line item stays two lines, a gnarly one gets a page. Two items owe one sentence each, which a two-line body can carry: a `later` names the unknown that would settle its value decision, and a `no` records why the fix was rejected, without which it cannot do the anti-rediscovery job it is kept for.

Lifecycle

Create the file. When the work lands, `git rm` it in the commit that lands the fix — not a separate cleanup commit. There is no checkbox, no in-progress marker: the staged deletion is the state. Dropping an item decided against is the same operation with a different reason.

Briefing an item

Both argument forms below put the same four things on screen before asking anything about an item, as ordinary output rather than inside the `AskUserQuestion`. The widget covers roughly five lines above itself, so the question text still names the item and carries the one-line reason for its recommendation.

• **Summary** — what the item is and why it was filed, in your own words, one or two sentences. Not the

H1 restated and not the body pasted back.

• **Effort** — what the fix costs: the files and call sites it touches, whether a test already covers the

path, and whether it is mechanical or a design decision still to be made.

• **Blast radius** — what else the change can reach. Callers, generated files, anything sharing the code

path, and whether it reverts cleanly. "Contained" is a claim about what depends on the code, so check before making it.

• **Materiality** — who is affected today, how badly, and what leaving it costs. Most items have no

user-visible symptom; say so rather than inflating one.

Each of the last three is ONE line carrying a word and the fact behind it — the word alone asks the user to take the call on trust, the fact is what lets him disagree with it, and the length is what keeps the briefing readable above its question. Judge all four against the repo as it stands rather than against the item's own account: the reasoning in a file goes stale the same way its `where` does.

Every item as the argument

`/workflow:backlog --all` walks every current item to a disposition. Check this mode before slug handling. An argument that starts with `-` is option syntax, so a file whose name begins with `-` cannot be reached as a slug; `all.md` is still an ordinary slug and unaffected.

1. Glob `docs/backlog/*.md` from the repo root and read every file in full. Keep `worth: no` items in the walk: worth informs the recommendation, it does not filter the list. 2. Before asking anything, verify every `where` and analyze each item's value, complexity, and blockers. Identify explicit blockers and relationships between items, ask about real prerequisites before their