cc-refactoring-guidance

Skill: cc-refactoring-guidance

STOP - Refactoring Rules

• Fix first, then refactor - Never simultaneously (separate commits)
• Small changes need MORE rigor, not less - 1-line changes have HIGHEST error rate
• >50% of changes fail first attempt - Review and test even "trivial" changes

---

Quick Reference

Rule	Value	Source
Small change error rate	Peaks at 1-5 lines	Weinberg 1983
First attempt success rate	<50% for any change	Yourdon 1986b
Review effect on 1-line changes	55% -> 2% error rate	Freedman and Weinberg 1982
Big refactoring	"Recipe for disaster"	Kent Beck

Key Principles:

• Refactoring = behavior-preserving changes to WORKING code
• Fix first, then refactor (never simultaneously)
• Small changes need MORE rigor, not less
• Sometimes rewrite is better than big refactoring

Critical: Each change has >50% first-attempt error rate regardless of prior results. Error rates are per change, not cumulative.

Definitions:

• small = ONE structural change (one rename, one extract, one inline). If you describe it with "and", it's not small.
• review = distinct person examining diff. Self-review does NOT satisfy this. AI review is acceptable but less effective.
• working code = all tests pass AND no known behavior bugs. Code that compiles but has failing tests is NOT working.
• then (as in "fix first, then refactor") = with COMMIT BOUNDARY between activities. Not same session, same commit.

---

Pattern Reuse Gate

BEFORE starting any refactoring, identify target patterns:

Search For	Why
Best examples of this pattern	What does "good" look like in this codebase?
Similar refactorings done before	How were they structured?
Module/directory conventions	What patterns dominate this area?
Recent improvements	What direction is the code evolving?

Questions to answer:

1. What pattern am I refactoring TOWARD? (Not just away from bad code)
2. Does this target pattern exist elsewhere in the codebase?
3. Am I aligning with the codebase's direction, or fighting it?
4. Will this make surrounding code look inconsistent?

If target pattern exists: Match it exactly. Copy naming, structure, style.

If no target pattern exists: You're establishing one. Consider:

• Is this the right time to set a new precedent?
• Should you refactor MORE code to establish the pattern consistently?
• Document the new pattern for future reference.

See: pattern-reuse-gate.md for full gate protocol.

---

Core Patterns

Pattern 1: Mixing Fix and Refactor -> Separate Commits

// BEFORE: Mixing concerns [ANTI-PATTERN]
// "I'm just cleaning while I fix the bug"
- Modified broken code
- Added refactoring changes
- Single commit with mixed purposes

// AFTER: Separated activities
1. Fix the bug (verify working)
2. Commit fix
3. Refactor working code
4. Commit refactoring

Pattern 2: Casual Small Change -> Rigorous Small Change

// BEFORE: Treating 1-line change casually [ANTI-PATTERN]
- Skip desk-check ("it's just one line")
- Skip review ("overkill for this")
- Skip testing ("obviously correct")

// AFTER: Small change rigor
- Desk-check even 1-line changes
- Get review (55% -> 2% error rate)
- Run regression tests
- Apply same rigor as large changes

Pattern 3: Documenting Bad Code -> Rewriting It

// BEFORE: Adding comment to explain confusion [ANTI-PATTERN]
// Note: This calculates X by doing Y because of Z edge case
// which happens when A and B are both true and C is false
complicated_obscure_code();

// AFTER: Self-explanatory rewrite
clear_function_that_explains_itself();

Modes

APPLIER

Purpose: Guide refactoring decisions and safe refactoring process Triggers:

• "should I refactor or rewrite this?"
• "how should I approach improving this code?"
• "is this safe to refactor?" Non-Triggers:
• "fix this bug" -> Fix first, then come back for refactoring
• "review this refactoring" -> Use code review skill
• "check my code style" -> cc-control-flow-quality

Emergency Response (Production Down)

When production is down:

1. Fix ONLY - No refactoring. No cleanup. Just fix the bug.
2. Deploy the fix - Get production up.
3. THEN refactor - As separate activity when stable.

Combining fix and refactor in one change increases complexity and error likelihood. Split them.

When Prerequisites Are Missing

No automated tests:

1. Invoke Skill(code-foundations:welc-legacy-code) — follow the Legacy Code Change Algorithm
2. Write characterization tests first (capture current behavior, not intended behavior)
3. If impossible: document expected behavior, manual test script, increase review rigor
4. Minimum: at least one verification path must exist

No version control:

1. Create physical backup copy of files before starting
2. STRONGLY recommend: set up VCS first. This is almost always the right choice.

No reviewer available:

1. Perform systematic checklist-based self-review
2. Smaller changes, more commits, more testing to compensate

Refactoring vs Rewriting Decision

1. Does code currently work?
   NO  -> This is FIXING, not refactoring. Fix first.
   YES -> Continue

2. Is the design fundamentally sound?
   NO  -> Consider REWRITING from scratch
   YES -> Continue

3. Would changes touch >30% of module?
   YES -> "Big refactoring" - consider rewrite
   NO  -> Proceed with incremental refactoring

Safe Refactoring Process (Priority Order)

1. Save starting code - Version control checkpoint
2. Keep refactorings small - One change at a time
3. Make a list of steps - Plan before executing
4. Do one at a time - Recompile and retest after each; STATE: "Tests pass after [change]"
5. Use frequent checkpoints - Commit working states
6. Enable all compiler warnings - Pickiest level
7. Retest after each change - Run tests, report results (not just "tests pass")
8. Review changes - Required even for 1-line changes
9. Adjust for risk - Extra caution for high-risk changes

Refactoring Sequencing (Fowler):

• Move Field BEFORE Move Method (data first)
• Extract Method BEFORE Replace Temp with Query
• Self Encapsulate Field BEFORE Replace Data Value with Object
• Replace Constructor with Factory Method BEFORE Replace Type Code with Subclasses

Recovery if Tests Fail After Refactoring:

1. Don't debug extensively
2. Back out the change
3. Take a smaller step
4. Consider if you understood the code correctly

Produces: Refactoring approach, step sequence, risk assessment Constraints:

• [p.565] Refactoring requires WORKING code as starting point
• [p.571] Treat small changes as if they were complicated
• [p.579] "A big refactoring is a recipe for disaster" - Beck

TRANSFORMER

Purpose: Transform code smells into clean code Triggers:

• Code smell identified during review
• "clean up this setup/takedown pattern"
• "eliminate this tramp data" Non-Triggers:
• Behavior changes needed -> Fix first
• New feature addition -> Not refactoring

Input -> Output:

• Setup/takedown smell -> Encapsulated interface
• Tramp data (passed just to pass again) -> Direct access or restructure
• Duplicated code -> Extracted shared routine
• Speculative "design ahead" code -> Remove it Preserves: All observable behavior Verification: Same tests pass before and after

Already Violated? Here's What To Do

If you mixed fix and refactor in one commit:

• Before push: git reset --soft HEAD~1, separate changes, re-commit properly. Takes ~15 minutes.
• After push: Document the violation, split in follow-up PR. Don't force-push shared branches.
• Never: Leave it because "it's already done."

If you skipped review on a small change:

• Before merge: Get the review now. It's not too late.
• After merge: Note it, move on, don't skip next time.

Fixing violations post-commit is still worthwhile — the cost of fixing now is less than the debugging cost of bugs they cause.

---

Chain

After	Next
Refactoring complete	cc-control-flow-quality (CHECKER)
Structure changed	cc-routine-and-class-design (CHECKER)