remove-technical-debt

What it does

Guides a user through a phased, interactive process to pay down technical debt in a large legacy codebase without a big rewrite. It coordinates eight underlying skills (working-with-legacy-code, refactoring-patterns, clean-code, software-design-philosophy, clean-architecture, pragmatic-programmer, release-it, domain-driven-design), prompting questions at each decision point and recording results in project docs/ (TESTING.md, TECH-DEBT.md, REMOVE-TECHNICAL-DEBT-PLAN.md) so progress persists across sessions. It starts by building a safety net, then progressively applies small, behavior-preserving changes with tests, documenting outcomes in the docs/ folder and updating a tracker. It emphasizes not touching code absent from a Safety Net Map in Phase 1, and structures work so you can resume later with a tracker in place.

How it works

• Phase 1 (working-with-legacy-code): Invokes the phase with the starting module chosen at intake. It asks for an effect sketch, pinch points, seams to break, and a minimal characterization-test set. It creates docs/TESTING.md with sections for Test Strategy and Safety Net Map, and docs/TECH-DEBT.md with Debt Ledger and Sprout/Wrap Register. It requires that the target module's behavior is pinned and tests green before unlocking Phase 2.
• Phase 2 (refactoring-patterns): Names and applies small, behavior-preserving transformations one at a time, each backed by tests, and records results in docs/TECH-DEBT.md under Smell Inventory (location, refactoring, status). It may propose a Branch by Abstraction plan for large migrations.
• Phase 3 (clean-code): Improves legibility with clearer names, small single-purpose functions, safer error handling, and a dedicated error-handling audit. Updates docs/TECH-DEBT.md with Smell Inventory rows and Adopted Conventions.
• Phase 4 (software-design-philosophy): Reduces complexity by hiding machinery behind interfaces, consolidating deep modules, and minimizing information leakage. Logs consolidations and conventions in docs/TECH-DEBT.md.
• Phase 5 (clean-architecture): Ensures business rules govern dependencies, using dependency inversion between use cases and adapters; maps the dependency graph and identifies violations.
• Phase 6 (pragmatic-programmer) onward: Subsequent phases extend documentation and enforce practices to prevent debt re-accumulation, with artifacts stored in docs/ and tracker updates.

When to use it

Use when you want to tame a legacy codebase, pay down technical debt safely, avoid a big-bang rewrite, or address fear of touching the code. The skill recommends using specific complementary skills (e.g., improve-code-quality, design-code-architecture, improve-app) for related scenarios and provides explicit phase-based flow before touching code.

What it can touch

Uses phase-specific invocations like working-with-legacy-code, refactoring-patterns, clean-code, software-design-philosophy, clean-architecture, pragmatic-programmer, release-it, and domain-driven-design to operate, along with updates to docs/TESTING.md, docs/TECH-DEBT.md, docs/REMOVE-TECHNICAL-DEBT-PLAN.md and the tracker in the project.

Caveats

Phase 1 must pin behavior before any changes; phase commits are single-purpose and pinned tests must pass to progress. Bugs found during characterization are to be pinned in the Debt Ledger, not fixed silently. Phase entries may be deferred for gating phases, and artifacts are stored as uppercase files in docs/.