# Remove Technical Debt

> Pay down debt in place without stopping shipping — a guided journey that orchestrates 8 AI agent skills, one decision at a time.

Published 2026-07-16 · Updated 2026-08-17 · Guided journey · Free and MIT-licensed
Canonical: https://skills.wondel.ai/skills/remove-technical-debt/
Source: https://github.com/wondelai/skills/tree/main/remove-technical-debt
Companion guide: https://skills.wondel.ai/guides/refactor-a-codebase-buried-in-technical-debt/

**Install:** `npx skills add wondelai/skills/remove-technical-debt --global`

## 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.

## The 8 phases

1. **Legacy Code** _(gate)_ — Can I change this code without breaking it unknowingly, and where do I start? → `docs/TESTING.md + docs/TECH-DEBT.md` (https://skills.wondel.ai/skills/working-with-legacy-code/)
2. **Refactoring** — Can I reshape structure without changing behavior? → `docs/TECH-DEBT.md` (https://skills.wondel.ai/skills/refactoring-patterns/)
3. **Clean Code** — Is what I touch legible to the next reader and agent? → `docs/TECH-DEBT.md` (https://skills.wondel.ai/skills/clean-code/)
4. **Software Design** — Is complexity hidden behind deep modules? → `docs/TECH-DEBT.md` (https://skills.wondel.ai/skills/software-design-philosophy/)
5. **Clean Architecture** — Do business rules depend on the framework, or vice versa? → `docs/ARCHITECTURE.md` (https://skills.wondel.ai/skills/clean-architecture/)
6. **Pragmatic Programmer** — What habits stop debt from re-accumulating? → `docs/TECH-DEBT.md` (https://skills.wondel.ai/skills/pragmatic-programmer/)
7. **Release It!** — Will it survive a hostile production? → `docs/RELIABILITY.md` (https://skills.wondel.ai/skills/release-it/)
8. **Domain-Driven Design** — How do I carve the monolith into bounded contexts? → `docs/ARCHITECTURE.md` (https://skills.wondel.ai/skills/domain-driven-design/)

## What it produces

- `docs/TESTING.md`
- `docs/TECH-DEBT.md`
- `docs/ARCHITECTURE.md`
- `docs/RELIABILITY.md`
- `docs/REMOVE-TECHNICAL-DEBT-PLAN.md`

## When 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.

## Example prompts

- Our codebase is a minefield nobody dares touch — dig us out. using remove-technical-debt skill _(Afraid to touch it)_
- Start the tech-debt journey: pick the starting module and build the safety net. using remove-technical-debt skill _(Starting the journey)_
- Continue the debt paydown from the tracker. using remove-technical-debt skill _(Resume journey)_

## Worked example — 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.
```

## 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.