Remove Technical Debt
Pay down debt in place without stopping shipping
Takes you from a large aged codebase everyone fears to touch to one that is safe to change, legible, bounded, and resilient - paid down in place without a rewrite. It orchestrates its eight skills phase by phase, asking you the decision questions at every step and recording every result in your project's docs/ folder so the journey resumes across sessions.
npx skills add wondelai/skills/remove-technical-debt --global - 01
Can I change this code without breaking it unknowingly, and where do I start? gate
Legacy Code → docs/TESTING.md + docs/TECH-DEBT.md - 02
Can I reshape structure without changing behavior?
Refactoring → docs/TECH-DEBT.md - 03
Is what I touch legible to the next reader and agent?
Clean Code → docs/TECH-DEBT.md - 04
Is complexity hidden behind deep modules?
Software Design → docs/TECH-DEBT.md - 05
Do business rules depend on the framework, or vice versa?
Clean Architecture → docs/ARCHITECTURE.md - 06
What habits stop debt from re-accumulating?
Pragmatic Programmer → docs/TECH-DEBT.md - 07
Will it survive a hostile production?
Release It! → docs/RELIABILITY.md - 08
How do I carve the monolith into bounded contexts?
Domain-Driven Design → docs/ARCHITECTURE.md
Each phase asks the question, then writes the answer before the next one starts.
The long read behind the phases: How to Refactor a Codebase Buried in Technical Debt
02 What it is
What is the Remove Technical Debt journey?
No rewrite, no freeze — debt gets paid down in place while you keep shipping. Eight phases start with a safety net around the scariest module, then apply named refactorings, restore legibility, hide complexity, redraw dependencies, harden production and carve bounded contexts, logging every call in docs/ as you go.
03 In practice
Dig a Codebase Out of Technical Debt
Every change breaks something, nobody dares touch the core, and a rewrite is off the table.
Our codebase is buried in debt: every change breaks something and nobody dares touch the core. Run the remove-technical-debt journey — characterization tests before any change, named refactorings, boundaries, and a debt ledger in docs/TECH-DEBT.md. We keep shipping throughout.
Use remove-technical-debt skill.
Written to your repo
- docs/TESTING.md
- docs/TECH-DEBT.md
- docs/ARCHITECTURE.md
- docs/RELIABILITY.md
- docs/REMOVE-TECHNICAL-DEBT-PLAN.md journey tracker
Stop anytime. The tracker records which phases are done and which decision is next, so a new session opens at the unanswered question.
04 Prompts
Say it like this.
Name the journey at the end of a prompt and it takes over from phase one. Say it again in a later session and it resumes at the unanswered question.
Our codebase is a minefield nobody dares touch — dig us out. using remove-technical-debt skill
Start the tech-debt journey: pick the starting module and build the safety net. using remove-technical-debt skill
Continue the debt paydown from the tracker. using remove-technical-debt skill
05 Fit
One prompt runs it.
Every phase asks before it acts, and every decision lands in your project's docs/ folder as a living document.
Reach for it when
Tame a large, aged codebase the team is afraid to change
Build a characterization-test safety net before any refactoring
Work smells down with named, behavior-preserving refactorings
Draw dependency boundaries and carve bounded contexts without a rewrite
Keep a debt ledger with priorities instead of a vague "cleanup" wish
Reach for something else when
The repo is a small AI-generated prototype heading for launch. Improve Code Quality is the faster route.
You already have tests and want one named transformation applied. install Refactoring on its own.
The plan is a green-field replacement rather than in-place paydown. Design Code Architecture is where that starts.
The system is fine but the product disappoints users. Improve an App works on what people actually feel.
07 Questions
Before you install.
How do I install the Remove Technical Debt journey?
Run npx skills add wondelai/skills/remove-technical-debt --global. It takes about 30 seconds and needs no account. The Remove Technical Debt skill then works in Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw and Hermes Agent — anything that reads the open agentskills.io format — and your agent loads it on its own when a task calls for it. It is free and MIT-licensed, and the source is at https://github.com/wondelai/skills.
Which skills does the Remove Technical Debt journey run, and what does it produce?
It orchestrates 8 skills across 8 phases — Legacy Code, Refactoring, Clean Code, Software Design, Clean Architecture, Pragmatic Programmer, Release It!, Domain-Driven Design — asking you one decision question per phase. Each answer is written to your project's docs/ folder (docs/TESTING.md, docs/TECH-DEBT.md, docs/ARCHITECTURE.md, docs/RELIABILITY.md, docs/REMOVE-TECHNICAL-DEBT-PLAN.md), so the journey survives across sessions and you keep the reasoning, not just the output.
How do I choose the first module to attack?
The first phase asks exactly that, and the answer is not the worst module — it is the one where change is most frequent and most feared. Legacy Code scores candidates by churn and risk, writes the shortlist to docs/TECH-DEBT.md, and puts characterization tests around the winner before anything moves. Starting with the ugliest but rarely touched file is how debt programmes lose their sponsor by week three.
Can we keep shipping features while this runs?
That is the design. Every phase is scoped to something a single pull request can carry, and the gate keeps the safety net ahead of the change. Paydown happens in the modules feature work is already touching, so the two share context instead of competing for it. What the journey will not do is grant you a freeze — if a phase needs one to be safe, it says so and narrows the scope instead.
The last phase carves bounded contexts. Is that a microservices migration?
No. Domain-Driven Design here draws the seams — where the business genuinely splits, and what each term means on either side — and records them in docs/ARCHITECTURE.md. Those seams are useful whether they stay modules inside one deployable or become services later. Splitting the deployment is a separate decision the journey deliberately leaves open, because most teams get the boundary benefit without paying the distributed-systems cost.
How do I show progress to someone who does not read code?
docs/TECH-DEBT.md is written for that. It is a ledger — named smells, where they live, what they cost, what has been paid down — rather than a vague cleanup wish, and docs/REMOVE-TECHNICAL-DEBT-PLAN.md shows which of the eight phases are complete. docs/TESTING.md shows coverage arriving where there was none. Together they turn “the code is bad” into a list with a burn-down.
Eight skills, one deliberate order.
Run the whole journey with one prompt.
npx skills add wondelai/skills/remove-technical-debt --global MIT licensed · Claude, Claude Code, Codex, Cursor, OpenClaw, Hermes · No account