# Refactoring Analysis

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

- Skill: `compozy/refactoring-analysis` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add compozy/refactoring-analysis`
- Raw SKILL.md: https://api.skillmd.com/api/skills/compozy/refactoring-analysis/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: compozy (https://skillmd.com/u/compozy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/compozy/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.