refactoring-and-debt

Automate safe, incremental refactoring with one structural change per commit.

2|Updated Jan 3, 2026

Search Tags:#architecture #refactoring #code-quality #software-engineering #tests #technical-debt

Ready to run

npx skills add https://github.com/jlaws/dotfiles --skill refactoring-and-debt

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: refactoring-and-debt
Source: https://github.com/jlaws/dotfiles/tree/main/.agents/skills/workflow/refactoring-and-debt
Command: npx skills add https://github.com/jlaws/dotfiles --skill refactoring-and-debt

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Technical debt and messy refactors slow teams; this skill provides a disciplined approach to safely restructure code without changing behavior, improving long-term velocity.

Core Features & Use Cases

Cadenced refactoring workflow: perform a single structural change per commit, with tests and reviews to validate behavior.
Debt inventory and code-smell guidance to prioritize changes and track improvements over time.
Use Case: when a legacy module shows high coupling, apply this process to gradually extract responsibilities while preserving functionality.

Quick Start

Identify one safe refactor in the current module and implement it with a small, atomic commit.

Frequently Asked Questions about refactoring-and-debt

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I safely refactor legacy code with high coupling without changing behavior?▼

To safely refactor legacy code, apply a cadenced workflow of one structural change per commit, guided by full test verification and reviews to ensure behavior remains stable while gradually extracting responsibilities. This reduces complexity incrementally.

What's the best way to track and prioritize technical debt in a large codebase?▼

The best way to track technical debt is by maintaining a debt inventory and using code-smell guidance to prioritize changes, allowing you to measure improvements over time and target high-impact refactors that increase long-term velocity.

How do I structure commits when incrementally refactoring a complex module?▼

Structure commits during refactoring by making small, atomic changes where each commit represents a single structural modification, ensuring the codebase remains stable and verifiable through tests before moving to the next step.

Can I use this refactoring workflow for mid- to large-codebases across multiple teams?▼

Yes, this refactoring workflow is designed for mid- to large-codebases across teams, providing a structured process with commit discipline and reviews to guide developers through safe, incremental remediation of technical debt.

Do I need comprehensive tests before starting a structural refactor?▼

Yes, full test verification is required before starting structural refactoring to validate that behavior remains stable, ensuring the incremental changes reduce complexity without introducing regressions into the module.

Why does automated refactoring focus on small atomic commits?▼

Automated refactoring focuses on small atomic commits to ensure behavior remains stable, allowing developers to isolate structural changes, verify them through tests, and maintain a clear history of complexity reduction.