Refactoring Analysis

Procedures

1. Determine the analysis target — a specific directory, module, feature area, or the entire project. If the user did not specify, ask which area to focus on.
2. Identify the project's language and paradigm (OOP, functional, mixed) to calibrate which smells and techniques are applicable.
3. If the project follows domain-driven design (DDD) or hexagonal architecture, read

   references/solid-ddd-context.md

   for additional SOLID-specific analysis criteria.

1. Map the directory structure and identify key modules, entry points, and shared utilities.
2. Read the most critical files (entry points, core business logic, shared modules).
3. Identify the project's conventions: naming, file organization, test patterns, dependency injection approach.

references/code-smells-catalog.md

1. Bloaters — Long Functions (>15 lines of logic), Large Classes/Modules (>300 lines), Long Parameter Lists (>3 params), Data Clumps, Primitive Obsession.
2. Change Preventers — Divergent Change (one module changed for multiple unrelated reasons), Shotgun Surgery (one change touches 5+ files).
3. Dispensables — Duplicated Code, Dead Code, Speculative Generality, Lazy Elements, Comments as Deodorant.
4. Couplers — Feature Envy, Insider Trading (excessive data sharing between modules), Message Chains (>2 levels deep), Middle Man (>50% delegation).
5. Conditional Complexity — Nested Conditionals (>2 levels), Repeated Switches, Missing Guard Clauses, Complex Boolean Expressions.
6. DRY Violations — Near-identical code blocks, copy-pasted logic with minor variations, repeated parameter groups, duplicated constants or magic numbers.

• Record the exact file path and line range
• Classify the smell type (from the catalog)
• Assess severity:

  critical

  |

  high

  |

  medium

  |

  low

• Note the impact on maintainability, readability, or change cost

references/refactoring-techniques.md

1. Identify modules with high afferent coupling (many dependents — risky to change).
2. Identify modules with high efferent coupling (many dependencies — fragile).
3. Flag circular dependencies between modules.
4. Assess cohesion — modules that mix unrelated responsibilities are candidates for Extract Class or Split Phase.

1. Search for near-duplicate code blocks (>5 lines of similar structure).
2. Identify repeated constant values (magic numbers, repeated string literals).
3. Find repeated parameter patterns across function signatures.
4. Look for copy-pasted logic with minor variations that could be parameterized.
5. Propose extraction strategies: shared functions, constants files, parameter objects.

references/solid-ddd-context.md

• SRP: Classes/modules with multiple reasons to change
• OCP: Areas requiring modification (not extension) for new variants
• LSP: Subclasses that override to throw or no-op (Refused Bequest smell)
• ISP: Interfaces forcing implementers to stub unused methods
• DIP: High-level modules importing low-level implementations directly

1. Read

   assets/refactoring-report-template.md

   for the output template.
2. Rank all findings by a priority score combining:
   • Impact: How much does this hurt readability, maintainability, or change cost?
   • Frequency: How often is this pattern encountered in the codebase?
   • Effort: How much work to refactor? (low effort + high impact = do first)
3. Group findings into priority tiers:
   • P0 — Critical: Blocking future development, causing bugs, or high coupling
   • P1 — High: Significant maintenance burden, frequent pain point
   • P2 — Medium: Noticeable but manageable, worth addressing opportunistically
   • P3 — Low: Minor improvements, cosmetic, litter-pickup candidates
4. Generate the report following the template and save to:

   docs/_refacs/<YYYYMMDD>-<slug>.md

   where

   <slug>

   is a lowercase-hyphenated summary (e.g.,

   auth-module-cleanup

   ).
5. Create the

   docs/_refacs/

   directory if it does not exist.

1. Present a brief executive summary to the user with:
   • Total findings count by severity
   • Top 3-5 highest-impact opportunities
   • Suggested refactoring order (quick wins first, then high-impact)
   • Estimated complexity tier for each (trivial / moderate / significant)
2. Ask the user if they want to proceed with any specific refactoring.

Error Handling

• If the analysis target is too broad (>50 files), ask the user to narrow scope or confirm they want a high-level scan with sampling.
• If the project has no tests, warn that refactoring without test coverage is risky and recommend adding tests for critical paths before refactoring.
• If the project uses an unfamiliar framework or pattern, note this limitation in the report rather than guessing.
• If a smell is ambiguous (could be intentional design), flag it as "potential" and note the context that might justify the current structure.