First Principles Code Refactoring

What problem it addresses

When working in an unfamiliar codebase, asking “where should we refactor?” can lead to surface-level changes: too broad scope, mistaken debt, or treating generated code and thin adapters as core problems. This skill turns code optimization into a reviewable engineering workflow: align goals first, then focus on modules that actually justify investment.

How it works

It follows a Pre-Phase + four-phase process:

• Scope alignment: confirm analysis depth, focus areas, and boundaries to avoid indiscriminate full-repo scans.
• Reconnaissance: use explore.sh to summarize directory structure, tech stack, code size, Git health, engineering conventions, and debt signals, then confirm key findings with the user.
• Deconstruction: ask first-principles questions such as why a module exists, whether it would be designed the same way from scratch, and what would break if removed, to spot over-engineering, defensive redundancy, ghost dependencies, and misplaced abstraction.
• Audit: select dimensions such as readability, maintainability, and security based on project size, and mark red, yellow, or green risk signals.
• Roadmap: rank work from P0 to P3, prioritizing security, correctness, and stability before performance, dependency upgrades, and architectural changes, with a gradual replacement preference.

Boundaries

It is better suited to codebase upgrades that require technical judgment and team alignment than to simple formatting fixes or single-function cleanup. If test coverage is missing, add tests or explicitly state the risk first. For vague or shifting business goals, complete scope alignment before starting analysis.