pedronauck/refactoring-analysis

Refactoring Analysis

Audit a codebase against Martin Fowler's Refactoring (2nd ed.) and produce a prioritized report. Every finding names a smell, cites the real file:line you read it at, and maps to a Fowler technique — grounded in code you actually read, never generic advice. When a step names a reference, read it in full before producing that step's findings.

Steps

1. Scope. Fix the target — directory, module, feature area, or whole project; ask if the user did not say. Note the language and paradigm (OOP / functional / mixed) to calibrate which smells apply. If the target exceeds ~50 files, ask to narrow or confirm a sampled scan. Done when: target, language, and paradigm are recorded.

2. Detect smells. Scan for every category in references/code-smells-catalog.md, using its heuristics: Bloaters, Change Preventers, Dispensables, Couplers, Conditional Complexity, DRY Violations. For each hit record: file:line range, smell name + category, severity (critical / high / medium / low), and its cost to maintainability, readability, or change. Flag an ambiguous case as potential with the context that might justify it. Done when: every category above has been scanned, not only the ones that fired.

3. Map techniques. Give each smell its Fowler technique(s) from the table in references/refactoring-techniques.md, and sketch a concrete before/after for every P0 and P1 finding. Done when: each finding carries a named technique.

4. Assess coupling. Flag modules with high afferent coupling (many dependents — risky to change), high efferent coupling (many dependencies — fragile), circular dependencies, and low cohesion (mixed responsibilities → Extract Class / Split Phase). Done when: the dependency structure is characterized.

5. SOLID pass (domain projects only). Apply only when the project is domain-rich — DDD, hexagonal, or clean architecture; otherwise skip and note why in the report. references/solid-ddd-context.md holds the applicability gate, per-principle detection heuristics, and DDD checks — read it before this step. Done when: each principle has a concrete finding, or the skip and its rationale are recorded.

6. Prioritize and report. Rank findings by impact × frequency ÷ effort into tiers, P0 (critical / blocking) through P3 (minor / litter-pickup). Write the report from assets/refactoring-report-template.md and save to docs/_refacs/<YYYYMMDD>-<slug>.md (create the directory; <slug> is a lowercase-hyphenated summary, e.g. auth-module-cleanup). When the project has no tests, record in the report's risks that refactoring without coverage is unsafe and name the critical paths to cover first. Done when: the saved report matches the template and every finding sits in a tier.

7. Verify. Walk checklists/analysis-checklist.md; ship the report only once every item passes. Done when: the checklist is fully satisfied.

8. Present. Give the user a short summary: finding counts by severity, the top 3–5 opportunities, a suggested order (quick wins before high-impact structural work), and a complexity tier (trivial / moderate / significant) for each. Ask which refactoring to pursue.