# Debt

> 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.

- Skill: `theplenkov/debt` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add theplenkov/debt`
- Raw SKILL.md: https://api.skillmd.com/api/skills/theplenkov/debt/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: theplenkov (https://skillmd.com/u/theplenkov)
- Updated: 2026-11-17
- Page: https://skillmd.com/skills/theplenkov/debt

---


# /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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `bro plan run debt.toml`                                                 | Apply `[[verdicts]]` (the `debt set` states) as a batch plan — authoring schema `schemas/plans/debt.schema.json`; `bro plan describe debt` prints it (the example as a TOML template)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

## 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.

