Assess whether a codebase situation warrants refactoring and determine the right approach before any structural changes begin. Use this skill when a develope...
This skill runs before any code changes. It answers three questions:
1. **Should we refactor?** (Go / No-go)
2. **If yes, what approach?** (Opportunity trigger, Two Hats plan, session rules)
3. **What are the risks?** (Constraint inventory, stop conditions, backtrack rules)
**What this skill does NOT do:**
- It does not apply any refactoring transformations (use `method-decomposition-refactoring`, `conditional-simplification-strategy`, or other catalog skills for that)
- It does not diagnose specific code smells (use `code-smell-diagnosis` after this assessment)
- It does not plan a large multi-session effort (use `big-refactoring-planner` for codebase-scale work)
---
π‘ Examples
Example A: Feature Addition (Trigger B)
Situation: Adding promotional pricing to OrderProcessor. The method is 200 lines long, mixes fee calculation, tax computation, and discount application in a single block.
Assessment:
Trigger: B (Refactor when adding a feature)
Go: Yes β tests exist for current behavior, no published interface, no deadline this week
First hat: Refactoring
Hat-switch boundary: "When OrderProcessor has separate methods for fee calculation, tax computation, and discount application and all tests pass"
Goal: "Extract fee calculation into its own method so the promotional pricing hook has a single, clear insertion point"
Backtrack rule: "Any failing test I cannot explain in thirty seconds β revert to last commit"
Next step: Run code-smell-diagnosis on OrderProcessor, then apply method-decomposition-refactoring
Example B: Bug Fix (Trigger C)
Situation: Bug report: "discounts not applying correctly for international orders." Code mixes currency handling with discount logic in several places.
Assessment:
Trigger: C (Refactor when fixing a bug)
Conditional Go: Tests exist, but they do not cover international order paths β add tests first
First hat: Refactoring hat (to understand the code and make the logic visible)
Hat-switch boundary: "When the discount application logic is isolated and I can see exactly where the international order path diverges"
Goal: "Clarify the discount calculation path well enough that the bug becomes visible"
Stop condition: "Stop refactoring the moment the bug is visible β switch to adding-function hat to fix it"
Backtrack rule: Standard β revert to last passing state on any unexplained failure
Example C: Rewrite Candidate
Situation: Legacy billing module. Known to produce incorrect results in certain scenarios. Cannot write tests that pass because the existing behavior is wrong.
Assessment:
Trigger: None of A/B/C/D applies cleanly β the code does not work
No-Go for refactoring: Cannot stabilize the code before refactoring
Refactor vs. Rewrite: Evaluate component by component
- BillingCalculator: Rewrite β non-stabilizable, too broken to test
- InvoiceFormatter: Refactor β works correctly, poor structure only
- PaymentGatewayAdapter: Refactor β stable behavior, interface can be preserved
Next step: Isolate InvoiceFormatter and PaymentGatewayAdapter first; rewrite BillingCalculator behind a clean interface boundary
Example D: Deadline Proximity (No-Go)
Situation: Release is tomorrow. Developer wants to clean up the authentication module because it has been bothering them.
Assessment:
No-Go: Productivity gain from refactoring would land after the deadline, not before
Action: Make a note of the specific concerns (e.g., "AuthService.authenticate() is 150 lines mixing session management with credential validation"). Schedule refactoring for the next working day after release.
Rule: Even a "quick" refactoring near a deadline expands into unexpected scope. The right time to have done this was before the deadline pressure began.
