| name | refactoring-analysis |
| description | Audits a codebase for refactoring opportunities using Martin Fowler's code smell and technique catalog — long functions, duplication, high coupling, complex conditionals, primitive obsession — and writes a prioritized report to docs/_refacs/. Use when auditing code quality, planning a refactoring sprint, or reviewing architectural health; not for style/formatting, performance, or security audits.
|
| metadata | {"author":"Pedro Nauck","github":"https://github.com/pedronauck","repository":"https://github.com/pedronauck/skills"} |
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.
