deep-refactor-audit

Deep Refactor Audit

Overview

This is a no-code architecture audit for aggressively rethinking a codebase. The job is to ask why the codebase is shaped this way, whether that shape still deserves to exist, and what a strong principal engineer would change before allowing the system to keep growing.

AI-generated code often accumulates accidental architecture: features nobody asked to keep, abstractions created for one use case, hand-rolled versions of standard libraries, over-flexible configuration, compatibility paths with no owner, and names that hide what the code actually does. Treat those as suspect until they earn their place.

Core Stance

Because this audit does not modify production code, take intellectual risks. Be creative, skeptical, and specific. Question architecture, naming, feature value, user behavior, dependencies, and whether whole subsystems should exist.

Do not be polite at the expense of usefulness. The valuable output is not "some code smells exist." The valuable output is a clear opinion about what should be preserved, simplified, deleted, or redesigned.

Audit Boundary

Do not edit implementation files during this audit. You may create notes, diagrams, reports, and plans under docs/.

This restriction is not meant to make the audit timid. It exists so the diagnosis can be bolder than an implementation task.

Start By Setting A Goal

Before the deep dive, set an explicit audit goal. If the environment has a goal mechanism, use it. Otherwise write the goal at the top of the audit worklog.

Use this shape:

Goal:
Critically audit <scope> to determine which architecture, features, boundaries, names, abstractions, dependencies, and workflows should be preserved, simplified, removed, or redesigned.

Core questions:
- Why does this exist?
- Is it still needed?
- Is this the simplest shape that can support the product?
- Did this complexity come from real constraints or accidental accumulation?
- Is this hand-rolled code justified, or should it use a standard library/framework capability?
- What would the architecture look like if we designed it cleanly today?

Non-goals:
- Do not modify production code.
- Do not produce a shallow smell list.
- Do not assume the current architecture is justified.
- Do not recommend patterns without explaining concrete movement in the codebase.

Success criteria:
- Current architecture is mapped.
- Major boundaries are judged.
- Questionable features are called out.
- Hand-rolled machinery is compared against existing libraries or framework capabilities.
- Accidental complexity is separated from legitimate complexity.
- Prior art, named patterns, and mature repositories are researched where useful.
- A target architecture and refactor roadmap are written.