Engineering managers, founders, and consultants

Technical debt prioritization playbook

Debt work fails when it is framed as taste. It earns planning time when it is tied to risk, delivery drag, incidents, onboarding, and upcoming roadmap work.

Step 1

Group findings by risk type

A usable debt inventory is grouped by the kind of drag it creates, not by the tool that found it.

Security and dependency hygiene
Architecture coupling and dependency cycles
Test gaps around critical flows
Documentation, environment, and onboarding gaps

Step 2

Score impact and likelihood

High-impact, high-likelihood debt deserves attention even if the code is not ugly. Low-impact ugliness can wait.

User, revenue, or data-risk impact
Frequency of change in the affected area
Past incidents, regressions, or support load
Upcoming roadmap dependency

Step 3

Sequence by fix shape

The first cleanup sprint should reduce risk without requiring the team to pause product development.

Contain secrets, vulnerable dependencies, and critical test gaps first
Extract duplicated logic only where future work is already planned
Split large refactors into reviewable issues
Reserve rewrite discussions for cases with evidence

Step 4

Track score movement

A roadmap should show whether the codebase is getting easier or harder to change over time.

Re-run audits after cleanup batches
Track repeated findings and recurring hotspots
Attach score changes to planning notes
Keep accepted debt visible in GitHub issues

How to use this playbook

Before the review

Use this playbook to set scope before anyone starts fixing code. For engineering managers, founders, and consultants, the first win is making the review explicit: what repository is in scope, what decision the work supports, and which access gaps still prevent a confident recommendation.

During the audit

Start with "group findings by risk type" and keep notes tied to files, routes, jobs, dependencies, or configuration. A useful audit does not say "the repo feels risky"; it shows the evidence path and explains why that evidence changes priority, estimate, or owner confidence.

After the readout

Use "track score movement" as the handoff point. Findings should become a small plan with owners, acceptance criteria, and a clear split between urgent containment, scheduled cleanup, and risk the team intentionally accepts for now.

What CodeTruss should produce

Run CodeTruss when the manual checklist needs to become repeatable: architecture map, health scores, source-backed findings, shareable report, GitHub issues, and optional fix PRs. The point is to shorten discovery while keeping the final decision evidence-based.

When the playbook is complete

Stop when the next decision is clear. A finished playbook should say whether to proceed, pause, contain risk, create issues, or gather missing access. It should not expand into open-ended cleanup. The output is a narrow, evidence-backed path to action.

What to re-check later

Revisit the playbook after the next scan, release, or cleanup batch. If the same risk appears again, the team needs a process change, not another one-off note.

Evidence to collect

Debt score trend and recurring finding list
Files with high churn plus high complexity
Critical-path test gaps and accepted risk notes
Issue roadmap grouped by 30/60/90-day sequence

Mistakes to avoid

Ranking debt by engineer annoyance instead of business or delivery risk
Creating one giant cleanup epic that nobody can review
Using a score as a grade instead of a trend line
Separating debt work from the same planning board as product work

Related guides

Sources and standards

Run this playbook on a real repository

CodeTruss builds the architecture map, health scores, ranked findings, report, GitHub issues, and opt-in fix PRs from the repository itself.

Start free View report template