Guided Journey · Engineering

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.

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, resume any session

One prompt runs it

Every phase asks before it acts, and every decision lands in your project’s docs/ folder as a living document — quit anytime, resume in any session.

Use it when you need to
  • 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
Install this metaskill
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.

Journey Map

8 phases, one deliberate order

Each phase invokes one skill from the library, asks you the decision question, and writes the answer to your project’s docs/ before moving on.

  1. 01 Can I change this code without breaking it unknowingly, and where do I start? Legacy Code working-with-legacy-code → docs/TESTING.md + docs/TECH-DEBT.md Gate
  2. 02 Can I reshape structure without changing behavior? Refactoring refactoring-patterns → docs/TECH-DEBT.md
  3. 03 Is what I touch legible to the next reader and agent? Clean Code clean-code → docs/TECH-DEBT.md
  4. 04 Is complexity hidden behind deep modules? Software Design software-design-philosophy → docs/TECH-DEBT.md
  5. 05 Do business rules depend on the framework, or vice versa? Clean Architecture clean-architecture → docs/ARCHITECTURE.md
  6. 06 What habits stop debt from re-accumulating? Pragmatic Programmer pragmatic-programmer → docs/TECH-DEBT.md
  7. 07 Will it survive a hostile production? Release It! release-it → docs/RELIABILITY.md
  8. 08 How do I carve the monolith into bounded contexts? Domain-Driven Design domain-driven-design → docs/ARCHITECTURE.md
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 [age]-year-old codebase is buried in debt: [paste symptoms].
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.
Example Prompts

Try these with the skill installed

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
The Source

Born from a guide

This journey packages the playbook below as a single skill — the guide is the long-form read behind every phase.

Deep dive · Engineering

How to Refactor a Codebase Buried in Technical Debt

A safe, incremental plan for taming a legacy codebase — characterization tests, seams, named refactorings, and boundaries — using AI agent skills from Working Effectively with Legacy Code, Refactoring, Clean Architecture, and more.

18 min read
More Journeys

Twelve journeys, one library

Engineering

Improve Code Quality

9 phases Engineering

Design Code Architecture

8 phases Create · Business

Create a Business

10 phases Create · Website

Create a Website

10 phases Create · App

Create an App

10 phases Improve · Business

Improve a Business

8 phases Improve · Website

Improve a Website

8 phases Improve · App

Improve an App

9 phases Grow · Business

Grow a Business

9 phases Grow · Website

Grow a Website

8 phases Grow · App

Grow an App

8 phases

Install Remove Technical Debt

Free, open-source, and ready in 30 seconds.

npx skills add wondelai/skills/remove-technical-debt --global
Browse on GitHub See All Skills

MIT Licensed · Works with Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw, Hermes Agent & other agentskills.io agents · No account needed

Prove it

Don’t guess your AI engineering level.
Measure it.

25 questions · ~8 min · Free

For hands-on developers

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 & founders

CTO 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 org
Work with us

We build the skills you already use. Now we’ll build yours.

Custom skills · Subagents · MCP integrations — shipped to production, not demoed.

See what we build Book a 15-min call

Sprints from $3K · shipped to production, or you don’t pay the final milestone.