---
name: track-backlog
description: View and manage the tracker backlog — show in-progress work, current priorities, sprint contents; triage untriaged items; promote ideas to ready; plan a sprint (big rocks + little rocks, parallel-safe). Use when the user says /track-backlog, "what's in progress", "show the backlog", "triage", "promote X", "plan a sprint", "what should we work on next".
argument-hint: [status | triage | promote <id> | sprint plan <name> | sprint show]
---

<!-- GENERATED by the WorkQuarry installer — do not hand-edit. Edit the source in the workquarry submodule and re-run install.py. -->


# track-backlog — query and manage the backlog

Issue frontmatter (`tracker/issues/*.md`) is the database; all reads and writes go
through `tools/track.py`. Never hand-edit BACKLOG.md (generated) or frontmatter
status fields (use `set`). Process reference: `tracker/readme.md`.

## Operations (pick by argument or intent)

### status (default, no argument)
Show the working picture, three short views:
```
python tools/track.py list --status in-progress
python tools/track.py list --sprint <current>        # if a sprint is active
python tools/track.py list --status ready --sort priority
```
Report: what's moving, what's queued, anything stale (in-progress with no recent
commits touching its area — flag, don't assume). Keep it to one screen.

### triage
```
python tools/track.py list --status idea --sort priority
```
For each untriaged item (`?` fields) or aging idea, propose: priority (severity ×
frequency × what it blocks), effort, risk, and promote/keep/drop. Present as a
short table of proposals; apply only what the user approves, via:
```
python tools/track.py set <id> --priority p2 --effort M --risk low [--status ready]
```
Recommend dropping ideas untouched for weeks with no champion — closing with
`--dropped` is cheap; the file remains greppable.

### promote <id>
Promotion = `idea` → `ready` ("an agent may pick this up"). Before flipping:
- priority/effort/risk must be real values, not `?`
- `feature`/`debt`/`bug` REQUIRE a `## Done means` section (2–5 verifiable
  statements) to exist in the body first — add it if missing before promoting
- `problem` needs no acceptance criteria (it closes with an ADR)
```
python tools/track.py set <id> --status ready --priority ... --effort ... --risk ...
```

### sprint plan <name>   (e.g. 2026-01-A)
A sprint is a **working set**, not a time-box: the batch of issues selected for
parallel execution now. Selection is not priority order alone — compose it:
1. **Big rocks** (1–3): highest impact `ready` items, typically L/M effort.
2. **Little rocks**: S/M items that fill gaps — quick wins, debt paydown, and
   items that de-risk future big rocks.
3. **Parallel safety**: check each candidate's `## Dependencies` section
   (blocked-by must be empty or done; "touches" must not collide with another
   sprint member — two agents editing the same area = merge pain). Prefer
   spreading across areas.
4. **Risk balance**: not all high-risk items at once; pair each risky item with
   sure things so the sprint always ships something.
Propose the set with one-line reasoning each; on approval:
```
python tools/track.py set <id> --sprint <name>     # for each member
```
Remove with `--sprint none`. Only one sprint should normally be active.

### sprint show
```
python tools/track.py list --sprint <name>
```
Plus per-item one-liner: on track / blocked / not started.

## Queries agents can use directly
```
python tools/track.py list --open --area <area> --format csv
python tools/track.py list --status ready --sort priority
python tools/track.py list --type debt
```

## Rules
- Every `set` regenerates BACKLOG.md — no manual index edits, ever.
- Don't change priorities silently: triage and promotion changes are proposed to
  the user first (exception: filing brand-new items, where the filer sets initial values).
- Closing items goes through `python tools/track.py close <id> --outcome "..."`
  (banner + archive the plan doc; see readme lifecycle step 4).