Recipe: Tech debt ledger writer
A repeatable workflow for capturing, triaging, and scheduling tech debt so it stops accumulating silently. Ship faster by making debt visible.
Step 1 — Capture
When you spot a shortcut during code review or debugging, write one sentence in a shared ledger. Include the file path, the hack, and the risk it carries. No judgement — just record it.
Hardcoded JWT secret in dev — will break rotation. Risk: medium.
Step 2 — Triage
Weekly, sort entries by blast radius. Tag each as now, next, or later. If an entry sits in later for three cycles, either delete it or promote it — debt that never gets paid is just noise.
Step 3 — Schedule
Reserve 10% of every sprint for ledger items tagged now. Treat them as first-class tickets. The goal is not zero debt — it is debt you control.
Step 4 — Retro
At sprint close, count entries added vs resolved. If the ledger grows for three consecutive sprints, the team is borrowing against velocity. Raise the flag before it compounds.
Tooling tip
A Markdown file in the repo root works. For teams over four people, a lightweight GitHub Project board with an automated intake label scales better. The format matters less than the habit.