Any time a change deliberately skips scope to stay minimal (skip a case that can't
happen yet, defer a generalization, leave a rough edge for a known reason), leave a
one-line marker at the spot instead of just remembering it:
// DEBT: no pagination yet — fine while catalog is <500 items, revisit if it grows
# DEBT: hardcoded 3-retry limit, should read from config once multi-tenant lands
DEBT: <reason> — any comment syntax, always that exact token + colon + a reason. This
skill finds them; nothing else about how you write code needs to change.
What this skill does
- Find markers. In a git repo:
git grep -n "DEBT:" (respects .gitignore,
skips vendor/, node_modules/, binary files automatically). Outside a git repo:
grep -rn "DEBT:" --exclude-dir={vendor,node_modules,.git}.
- Attribute each hit. For tracked files,
git blame -L <line>,<line> --porcelain <file>
to get commit sha, author, and date — best effort, skip silently if blame fails
(uncommitted file, binary, etc.).
- Diff against the existing ledger at
.claude/debt-ledger.md (create if absent).
Match prior entries by file:line + marker text:
- NEW — marker found now, not in the previous ledger.
- STILL OPEN — marker found now and was in the previous ledger (carry its
original "first seen" date forward, don't reset it).
- RESOLVED — was in the previous ledger, marker no longer found in the code
(comment removed or line changed) — move it to a "Resolved" section with today's
date rather than deleting it, so the history of what got paid down is visible.
- Write the ledger. Overwrite
.claude/debt-ledger.md with:
- A one-line summary count (
N open, M resolved) at the top.
- An "Open" table sorted oldest-first:
file:line | reason | first seen | commit.
- A "Resolved" table (most recent first, capped at the last 20 — older resolved
entries can be found via git history on the ledger file itself, don't let this
section grow unbounded).
- Report. Print the same summary counts to the conversation, and call out any
entry open for a long time (no fixed threshold — use judgment: something first-seen
months ago with no movement is worth flagging explicitly, not just left in the table).
Notes
- This is a harvesting/reporting skill only — it never edits the DEBT-marked code
itself or removes markers. Paying down the debt is a separate, deliberate task.
- If
.claude/debt-ledger.md doesn't exist yet and no markers are found either, say so
plainly and stop — don't create an empty ledger file for a repo that isn't using the
convention yet.
1---2name: debt-ledger3description: Harvest deferred-shortcut markers (`DEBT: <reason>`) left in code across the current repo into a tracked ledger at `.claude/debt-ledger.md`, so a scope cut made to keep a change minimal doesn't silently become permanent. Use when the user says "harvest debt markers", "check deferred debt", "what shortcuts did we defer", "update debt ledger", or invokes /debt-ledger. Language-agnostic (matches the marker text, not any one comment syntax) — works across PHP, JS, Python, shell, etc.4---56Any time a change deliberately skips scope to stay minimal (skip a case that can't7happen yet, defer a generalization, leave a rough edge for a known reason), leave a8one-line marker at the spot instead of just remembering it:910```11// DEBT: no pagination yet — fine while catalog is <500 items, revisit if it grows12# DEBT: hardcoded 3-retry limit, should read from config once multi-tenant lands13```1415`DEBT: <reason>` — any comment syntax, always that exact token + colon + a reason. This16skill finds them; nothing else about how you write code needs to change.1718## What this skill does19201. **Find markers.** In a git repo: `git grep -n "DEBT:"` (respects `.gitignore`,21 skips `vendor/`, `node_modules/`, binary files automatically). Outside a git repo:22 `grep -rn "DEBT:" --exclude-dir={vendor,node_modules,.git}`.232. **Attribute each hit.** For tracked files, `git blame -L <line>,<line> --porcelain <file>`24 to get commit sha, author, and date — best effort, skip silently if blame fails25 (uncommitted file, binary, etc.).263. **Diff against the existing ledger** at `.claude/debt-ledger.md` (create if absent).27 Match prior entries by `file:line` + marker text:28 - **NEW** — marker found now, not in the previous ledger.29 - **STILL OPEN** — marker found now and was in the previous ledger (carry its30 original "first seen" date forward, don't reset it).31 - **RESOLVED** — was in the previous ledger, marker no longer found in the code32 (comment removed or line changed) — move it to a "Resolved" section with today's33 date rather than deleting it, so the history of what got paid down is visible.344. **Write the ledger.** Overwrite `.claude/debt-ledger.md` with:35 - A one-line summary count (`N open, M resolved`) at the top.36 - An "Open" table sorted oldest-first: `file:line | reason | first seen | commit`.37 - A "Resolved" table (most recent first, capped at the last 20 — older resolved38 entries can be found via git history on the ledger file itself, don't let this39 section grow unbounded).405. **Report.** Print the same summary counts to the conversation, and call out any41 entry open for a long time (no fixed threshold — use judgment: something first-seen42 months ago with no movement is worth flagging explicitly, not just left in the table).4344## Notes4546- This is a harvesting/reporting skill only — it never edits the DEBT-marked code47 itself or removes markers. Paying down the debt is a separate, deliberate task.48- If `.claude/debt-ledger.md` doesn't exist yet and no markers are found either, say so49 plainly and stop — don't create an empty ledger file for a repo that isn't using the50 convention yet.
ProxiBlue