name: cc-refactoring-guidance
description: "Guide safe refactoring with research-backed discipline and small-change rigor. Produce refactoring approach, step sequence, and risk assessment. Use when modifying existing code, improving structure without changing behavior, or deciding between refactor, rewrite, or fix-first. Triggers on: code smells, technical debt, just cleaning while I fix, small change treated casually, regression from trivial change, one-line change errors, production down with cleanup urge."

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

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: Error rates are PER CHANGE, not per person. Your 10-change success streak does not reduce probability on change 11. Each change is an independent event with >50% first-attempt error rate.

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:

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.

Emergency pressure doesn't change error statistics—it makes them WORSE due to stress. "Fix AND clean up" requests during outages: split them. Fix first, deploy, clean up later.

When Prerequisites Are Missing

No automated tests:
1. Write characterization tests first (capture current behavior)
2. If impossible: document expected behavior, manual test script, increase review rigor
3. 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. Self-review with 24h delay (review your own changes after sleeping on it)
2. Rubber duck review (explain changes out loud, document the "conversation")
3. AI-assisted review (note: not equivalent to human review, but better than nothing)
4. Accept higher risk: smaller changes, more commits, more testing

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

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

Red Flags - STOP If You Think:

• "This is too simple to test"
• "I've already verified this mentally"
• "One commit is cleaner than two"
• "This change is isolated, can't affect anything"
• "The tests pass, so I'm done"
• "This is an emergency, I can skip steps"
• "My last N changes all worked perfectly"
• "I already did it differently but it works"

All of these mean: You're rationalizing. Follow the full rigor anyway.

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.

"It's too late" is almost never true. The discomfort of fixing violations is smaller than the debugging cost of bugs they cause.

Rationalization Counters

Chain