What it does
Tech Debt Ledger exists because technical debt is usually felt rather than measured. Everyone on the team can name the file they dread touching, but nobody can say what it costs, so it never makes it into a plan. You supply the per-file signals — change frequency, bug density, cyclomatic complexity and a remediation effort estimate in person-days — and the agent turns them into a scored, inspectable list. The metaphor is carried through deliberately. Each file gets an interest rate: 40% change frequency, 40% bug density, 20% complexity, each clamped against a fixed cap. Multiply that rate by the effort estimate — the principal — and you get the score. A file with a high interest rate is one you keep paying for every time you touch it. The formula, the weights, the normalisation caps and the tier thresholds are not buried in the code. They are plain constants, and they are echoed back inside every single result. That is the point rather than a nicety: a prioritisation nobody can inspect is a prioritisation nobody trusts, and the first question any engineering manager asks about a ranked list is why this file is above that one. From the scores it produces the hotspot files, a quarterly payment plan packed greedily against a capacity budget so the plan fits the quarter you actually have — and, importantly, it reports what did not fit rather than silently dropping it — plus draft Jira epics for the highest-priority items. Each step is callable alone. `hotspot_files` answers where to look first. `build_quarterly_plan` packs a plan from scores you already have. `build_jira_epics` produces the tickets. `run_full` does all of it. Scoring and planning are fully deterministic. The language model only narrates the root cause and the fix per finding, and never restates a number different from the one the model computed. The agent has no repository or Jira access and no write authority — the epics are drafts, and a human reviews the plan before it is actioned. No connectors and no credentials. Built for tech leads and engineering managers heading into quarterly planning.
Example prompts
- Here are our per-file debt signals — score them and build a Q3 plan
- Which files cost us the most every time we touch them?
- Pack a quarterly paydown plan for 20 engineer-days and tell me what didn't fit
