compozy 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.