`backlog.md`

The single ordered list of work the repo knows it still owes itself. Features, yes, but also the documentation, spec and decision debt that brownfield onboarding surfaced and nobody would otherwise write down.

Markdown, in the repo, agent-first. An agent can read it, append to it and re-order it without an API token, and it survives whatever tracker you are using this year.

What it is for

So that noticing something and not fixing it is a recorded act. That is the whole value. Mid-work you find a missing retry, a spec that lies, a dependency nobody chose. You are not fixing it in this pull request, and the alternatives are: remember it (you will not), fix it now (the pull request doubles), or say it out loud and move on.

What goes in here

One row per intent, each carrying who it is for, where it came from and what done looks like (the file itself declares more columns than this - see docs/backlog.md for the full row):

| Id | Intent | For whom | Source | Done when |
|---|---|---|---|---|
| INV-4 | Export retries on timeout | Ops lead Ola | asked: #212 | a timed-out export resumes without a manual replay |

An intent names its persona, because work that serves nobody is how a backlog becomes a graveyard - and internal work names the internal one rather than borrowing a customer. It names its source, one of five declared categories, because "every item has a source" is only a rule while it is a column somebody has to fill. And it names what done looks like, because an item without that never leaves: there is no moment at which anyone can say it is finished.

At the scale profile the file also carries an In flight section: which intents left the pool and into which sprint. An intent is in the pool or in exactly one sprint, never both, and sprint-guard fails the build when that stops being true. That table is why the pool stays the single place to start reading - so the guard checks the table too: each row must name a sprint that exists and is still open, and state how many intents it really holds.

What does not go in here

A mirror of your tracker. If you run a board as well, these are not two copies of one list: the repository holds the intents, the tracker holds execution history, and a one-way bridge joins them. Running without a board is also a real option - see backlog, sprints, timeline for where that line actually falls.

Ideas. "Should this exist at all" is docs/ideas/. A backlog intent is something already agreed to be worth doing.

Anything without a done condition. "Improve performance" is a feeling. "The export finishes under 30s for a 10k-row account" is an intent.

A custom backlog engine. The format is compatible with the Backlog.md tool if you want a board or a CLI on top. Building your own is a project that competes with the product.

How you actually use it

The most common case, and the one that decides whether the backlog is real or theatre:

> the booking export has no retry and dies on a timeout
  - not fixing it in this change, write it down so we do not lose it

You keep going. The agent files it with its source, the role that has to act, and what done means.

Decisions behind it

The backlog lives in the repo. A tracker was the alternative and it fails one specific way: the debt that brownfield onboarding surfaces is about the code, and it needs to be readable by the agent working in the code, at the moment it is working there.
Every intent names a persona and a done condition. Both were optional once. Optional meant absent, and absent meant a list that only grows.
ADR-028 - the pool and the sprints are one system. Letting an intent sit in both was the state before the guard existed, and it makes "what are we doing" unanswerable from the file.

Reference

Status. Required - part of the core profile.
How it arrives. fill-from-repo - scaffold the shell from the standard, then author the body from THIS repo's reality - never blind-copy the example prose (ARCHITECTURE, PRODUCT, specs)
Shipped form. None - this one is written into your repo during alignment, from your repo's own reality.

The rule that requires it

The repo backlog holds intents, each with a definition of done; an item

See it in the spec