gh-yaleh-meta-cc-claude/skills/code-refactoring/templates/refactoring-safety-checklist.md

Refactoring Safety Checklist

Purpose: Ensure safe, behavior-preserving refactoring through systematic verification

When to Use: Before starting ANY refactoring work

Origin: Iteration 1 - Problem P1 (No Refactoring Safety Checklist)

---

Pre-Refactoring Checklist

1. Baseline Verification

• All tests passing: Run full test suite (go test ./...)

  • Status: PASS / FAIL
  • If FAIL: Fix failing tests BEFORE refactoring

• No uncommitted changes: Check git status

  • Status: CLEAN / DIRTY
  • If DIRTY: Commit or stash before refactoring

• Baseline metrics recorded: Capture current complexity, coverage, duplication

  • Complexity: gocyclo -over 1 <target-package>/
  • Coverage: go test -cover <target-package>/...
  • Duplication: dupl -threshold 15 <target-package>/
  • Saved to: data/iteration-N/baseline-<target>.txt

2. Test Coverage Verification

• Target code has tests: Verify tests exist for code being refactored

  • Test file: <target>_test.go
  • Coverage: ___% (from go test -cover)
  • If <75%: Write tests FIRST (TDD)

• Tests cover current behavior: Run tests and verify they pass

  • Characterization tests: Tests that document current behavior
  • Edge cases covered: Empty inputs, nil checks, error conditions
  • If gaps found: Write additional tests FIRST

3. Refactoring Plan

• Refactoring pattern selected: Choose appropriate pattern

  • Pattern: _______________ (e.g., Extract Method, Simplify Conditionals)
  • Reference: knowledge/patterns/<pattern>.md

• Incremental steps defined: Break into small, verifiable steps

  • Step 1: _______________
  • Step 2: _______________
  • Step 3: _______________
  • (Each step should take <10 minutes, pass tests)

• Rollback plan documented: Define how to undo if problems occur

  • Rollback method: Git revert / Git reset / Manual
  • Rollback triggers: Tests fail, complexity increases, coverage decreases >5%

---

During Refactoring Checklist (Per Step)

Step N:

Before Making Changes

• Tests pass: go test ./...
  • Status: PASS / FAIL
  • Time: ___s

Making Changes

• One change at a time: Make minimal, focused change

  • Files modified: _______________
  • Lines changed: ___
  • Scope: Single function / Multiple functions / Cross-file

• No behavioral changes: Only restructure, don't change logic

  • Verified: Code does same thing, just organized differently

After Making Changes

• Tests still pass: go test ./...

  • Status: PASS / FAIL
  • Time: ___s
  • If FAIL: Rollback immediately

• Coverage maintained or improved: go test -cover ./...

  • Before: ___%
  • After: ___%
  • Change: +/- ___%
  • If decreased >1%: Investigate and add tests

• No new complexity: gocyclo -over 10 <target-file>

  • Functions >10: ___
  • If increased: Rollback or simplify further

• Commit incremental progress: git add . && git commit -m "refactor: <description>"

  • Commit hash: _______________
  • Message: "refactor: - "
  • Safe rollback point: Can revert this specific change

---

Post-Refactoring Checklist

1. Final Verification

• All tests pass: go test ./...

  • Status: PASS
  • Duration: ___s

• Coverage improved or maintained: go test -cover ./...

  • Baseline: ___%
  • Final: ___%
  • Change: +___%
  • Target: ≥85% overall, ≥95% for refactored code

• Complexity reduced: gocyclo -avg <target-package>/

  • Baseline: ___
  • Final: ___
  • Reduction: ___%
  • Target function: <10 complexity

• No duplication introduced: dupl -threshold 15 <target-package>/

  • Baseline groups: ___
  • Final groups: ___
  • Change: -___ groups

• No new static warnings: go vet <target-package>/...

  • Warnings: 0
  • If >0: Fix before finalizing

2. Behavior Preservation

• Integration tests pass (if applicable)

  • Status: PASS / N/A

• Manual verification (for critical code)

  • Test scenario 1: _______________
  • Test scenario 2: _______________
  • Result: Behavior unchanged

• Performance not regressed (if applicable)

  • Benchmark: go test -bench . <target-package>/...
  • Change: +/- ___%
  • Acceptable: <10% regression

3. Documentation

• Code documented: Add/update GoDoc comments

  • Public functions: ___ documented / ___ total
  • Target: 100% of public APIs

• Refactoring logged: Document refactoring in session log

  • File: data/iteration-N/refactoring-log.md
  • Logged: Pattern, time, issues, lessons

4. Final Commit

• Clean git history: All incremental commits made

  • Total commits: ___
  • Clean messages: YES / NO
  • Revertible: YES / NO

• Final metrics recorded: Save post-refactoring metrics

  • File: data/iteration-N/final-<target>.txt
  • Metrics: Complexity, coverage, duplication saved

---

Rollback Protocol

When to Rollback:

• Tests fail after a refactoring step
• Coverage decreases >5%
• Complexity increases
• New static analysis errors
• Refactoring taking >2x estimated time
• Uncertainty about correctness

How to Rollback:

1. Immediate: Stop making changes
2. Assess: Identify which commit introduced problem
3. Revert: git revert <commit-hash> or git reset --hard <last-good-commit>
4. Verify: Run tests to confirm rollback successful
5. Document: Log why rollback was needed
6. Re-plan: Choose different approach or break into smaller steps

Rollback Checklist:

• Identified problem commit: _______________
• Reverted changes: git revert _______________
• Tests pass after rollback: PASS / FAIL
• Documented rollback reason: _______________
• New plan documented: _______________

---

Safety Statistics (Track Over Time)

Refactoring Session: ___ (e.g., calculateSequenceTimeSpan - 2025-10-19)

Metric	Value
Steps completed	___
Rollbacks needed	___
Tests failed	___ times
Coverage regression	YES / NO
Complexity regression	YES / NO
Total time	___ minutes
Average time per step	___ minutes
Safety incidents	___ (breaking changes, lost work, etc.)

Safety Score: (Steps completed - Rollbacks - Safety incidents) / Steps completed × 100% = ___%

Target: ≥95% safety score (≤5% incidents)

---

Checklist Usage Example

Refactoring: calculateSequenceTimeSpan (Complexity 10 → <8) Pattern: Extract Method (collectOccurrenceTimestamps, findMinMaxTimestamps) Date: 2025-10-19

Pre-Refactoring

• All tests passing: PASS (0.008s)
• No uncommitted changes: CLEAN
• Baseline metrics: Saved to data/iteration-1/baseline-sequences.txt
  • Complexity: 10
  • Coverage: 85%
  • Duplication: 0 groups in this file
• Target has tests: sequences_test.go exists
• Coverage: 85% (need to add edge case tests)
• Pattern: Extract Method
• Steps: 1) Write edge case tests, 2) Extract collectTimestamps, 3) Extract findMinMax
• Rollback: Git revert if tests fail

During Refactoring - Step 1: Write Edge Case Tests

• Tests pass before: PASS
• Added tests for empty timestamps, single timestamp
• Tests pass after: PASS
• Coverage: 85% → 95%
• Commit: git commit -m "test: add edge cases for calculateSequenceTimeSpan"

During Refactoring - Step 2: Extract collectTimestamps

• Tests pass before: PASS
• Extracted helper, updated main function
• Tests pass after: PASS
• Coverage: 95% (maintained)
• Complexity: 10 → 7
• Commit: git commit -m "refactor: extract collectTimestamps helper"

Post-Refactoring

• All tests pass: PASS
• Coverage: 85% → 95% (+10%)
• Complexity: 10 → 6 (-40%)
• Duplication: 0 (no change)
• Documentation: Added GoDoc to calculateSequenceTimeSpan
• Logged: data/iteration-1/refactoring-log.md

Safety Score: 3 steps, 0 rollbacks, 0 incidents = 100%

---

Notes

• Honesty: Mark actual status, not desired status
• Discipline: Don't skip checks "because it seems fine"
• Speed: Checks should be quick (<1 minute total per step)
• Automation: Use scripts to automate metric collection (see Problem V1)
• Adaptation: Adjust checklist based on project needs, but maintain core safety principles

---

Version: 1.0 (Iteration 1) Next Review: Iteration 2 (refine based on usage data)