# Debt Ledger

> Debt Ledger

- Skill: `yuri-semenenko/debt-ledger` (Agent Skill)
- Install (CLI): `npx skillmds@latest add yuri-semenenko/debt-ledger`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yuri-semenenko/debt-ledger/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: yuri-semenenko (https://skillmd.com/u/yuri-semenenko)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yuri-semenenko/debt-ledger

---


# Debt Ledger

Surface every deliberate, named tradeoff in the codebase so accepted debt stays visible instead of rotting as an anonymous `// TODO`.

## Convention being collected

The persona's tradeoff annotation (see CLAUDE.md):

```
// TRADEOFF(ceiling: <what this solution maxes out at>; upgrade: <path when the ceiling is hit>): <short note>
```

The comment marker varies by language (`//`, `#`, `--`, `<!-- -->`). Match the `TRADEOFF(` token, not the comment syntax.

## Steps

1. **Grep** the repo for the `TRADEOFF(` token across source files (respect `.gitignore`; skip vendored/`node_modules`).
2. **Parse** each hit into: file, line, ceiling, upgrade path, note.
3. **Flag malformed annotations** — a `TRADEOFF` that omits `ceiling:` or `upgrade:` is incomplete; list it under a separate "needs detail" group rather than silently dropping it.
4. **Report** as a single ledger.

## Output

```
TRADEOFF ledger — <N> entries (<M> need detail)
```

| Location (`file:line`) | Ceiling | Upgrade path | Note |
|---|---|---|---|

Then a "needs detail" list for malformed entries. Do not editorialize or auto-fix — this is a read-only inventory. If zero annotations exist, say so plainly (it may mean the convention is not being used, not that there's no debt).