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.
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.
One prompt runs it
npx skills add wondelai/skills/remove-technical-debt --global This skill is compatible with Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw, Hermes Agent, and other agentskills.io-compatible agents.
Example prompts for the Remove Technical Debt journey
Our codebase is a minefield nobody dares touch — dig us out. using remove-technical-debt skill
Afraid to touch itStart the tech-debt journey: pick the starting module and build the safety net. using remove-technical-debt skill
Starting the journeyContinue the debt paydown from the tracker. using remove-technical-debt skill
Resume journeyWhen to use Remove Technical Debt — and when not to
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.
Frequently asked questions
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.
Install Remove Technical Debt
Free, open-source, and ready in 30 seconds.
npx skills add wondelai/skills/remove-technical-debt --global MIT Licensed · Works with Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw, Hermes Agent & other agentskills.io agents · No account needed
Don’t guess your AI engineering level.
Measure it.
AI Developer Scorecard
How production-grade is your AI engineering?
Twenty-five questions across the practices that separate vibe-coding from production-grade engineering. Instant score, per-section breakdown, and a 30/60/90-day playbook.
Score 0–75 · 30/60/90-day playbook Score yourself For CTOs & foundersCTO Scorecard
Is your engineering team ready for AI at scale?
Twenty-five questions on how your org adopts AI — adoption, governance, automation, and ROI. See where you sit on the path from Reactive to Strategic Leader.
Score 0–75 · Reactive → Strategic Leader Score your orgWe build the skills you already use. Now we’ll build yours.
Sprints from $3K · shipped to production, or you don’t pay the final milestone.