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.