---
name: debt
description: "Use when the user invokes /debt or asks about review debt on merged PRs. Thin wrapper over the bro CLI — all mechanics live in `bro review debt *` commands; this skill carries policy only. Requires `bro` (npx -y @broject/bro@0) and gh."
---

# /debt (bro)

**All mechanics live in the `bro` CLI.** This skill is policy only — do not
reimplement what `bro review debt` already does.

Prereq: `bro` on PATH or `npx -y @broject/bro@0` (major-pinned). Requires
`gh` auth; `bd` is required only with beads enabled (the default) —
`"stores": ["jsonl"]` in bro.config.json opts out and drops the `bd`
requirement.

## Commands

| Command | What it does |
| ------- | ------------ |
| `bro review debt collect [filters]` | Scan merged PRs **without** a `debt:*` label → collect unresolved threads → write `harvests/*.jsonl` → label `debt:collected` / `debt:clean`. With `debt.sources` in bro.config.json it also runs opt-in collectors (`dependabot`, `code-scanning`, `secret-scanning`, `stale-prs`, `failed-ci`, `sonarcloud`, `codacy`, `codescene`) — same ledger, `debt:<source>` labels on beads, `debt.stale_days` tunes stale-prs; `sonarcloud` needs `SONAR_TOKEN` + a project key (`debt.sourceConfig.sonarcloud.project_key` or `sonar-project.properties`); `codacy` needs `CODACY_API_TOKEN` or `CODACY_PROJECT_TOKEN`; `codescene` needs `CODESCENE_TOKEN` + `debt.sourceConfig.codescene.project_id` (or `CODESCENE_PROJECT_ID`) |
| `bro review debt status` | Ledger summary + unprocessed merged-PR count |
| `bro review debt stats [--by author\|source\|area]` | Signal per reviewer/source/area — fix% is the done share of decided rows |
| `bro review debt trend [--by author\|source\|area] [--bucket week\|day]` | Burn-down — open debt per time bucket (`--json` for chart data) |
| `bro review debt prs` | Merged PRs still unprocessed — the work queue (`--all`: full matrix) |
| `bro review debt list` | Ledger rows (`--status`, `--area`, `--author`, `--priority`, `--pr`) |
| `bro review debt mark <pr> <state>` | `collected` / `clean` / `skipped` / `none` — manual override |
| `bro review debt set <status> --thread-id ID` | Ledger status: `claimed` / `done --fix-pr N` / `wontfix` / `duplicate` — feeds `bro review debt sync` |
| `bro review debt sync` | Project the ledger into beads — `bd ready -l debt` becomes the work queue |

## Policy

- **`debt:*` labels are the PR-level source of truth** for "processed".
  `skipped` is a human opt-out and always wins over machine labels.
- **beads is a default store.** A normal collect auto-runs
  `bd init --stealth --skip-agents --skip-hooks` when `.beads` is missing
  (skipped by `--dry-run`, `--list-only`, and an empty ledger) —
  announced on stderr, never silent — and
  keeps the ledger dir out of git via `.git/info/exclude`.
  `"stores": ["jsonl"]` in bro.config.json is the opt-out.
- **Label after the file lands.** In CI pipelines run
  `collect --no-label`, land `harvests/*.jsonl` (`git add -f` — the ledger
  dir is locally excluded), then `bro review debt mark`.
- **Collect, don't fix.** Triage → backlog, fixes → the fix loop. `bro review debt` never edits product code or resolves threads on source PRs.
- `--reharvest` bypasses the label skip for one run.