Initial commit

2025-11-30 09:07:22 +08:00
commit fab98d059b
179 changed files with 46209 additions and 0 deletions
--- a/skills/code-refactoring/templates/refactoring-safety-checklist.md
+++ b/skills/code-refactoring/templates/refactoring-safety-checklist.md
@@ -0,0 +1,275 @@
+# 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: <Step Description>
+
+#### 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: <pattern> - <what changed>"
+  - 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
+- [x] All tests passing: PASS (0.008s)
+- [x] No uncommitted changes: CLEAN
+- [x] Baseline metrics: Saved to `data/iteration-1/baseline-sequences.txt`
+  - Complexity: 10
+  - Coverage: 85%
+  - Duplication: 0 groups in this file
+- [x] Target has tests: `sequences_test.go` exists
+- [x] Coverage: 85% (need to add edge case tests)
+- [x] Pattern: Extract Method
+- [x] Steps: 1) Write edge case tests, 2) Extract collectTimestamps, 3) Extract findMinMax
+- [x] Rollback: Git revert if tests fail
+
+### During Refactoring - Step 1: Write Edge Case Tests
+- [x] Tests pass before: PASS
+- [x] Added tests for empty timestamps, single timestamp
+- [x] Tests pass after: PASS
+- [x] Coverage: 85% → 95%
+- [x] Commit: `git commit -m "test: add edge cases for calculateSequenceTimeSpan"`
+
+### During Refactoring - Step 2: Extract collectTimestamps
+- [x] Tests pass before: PASS
+- [x] Extracted helper, updated main function
+- [x] Tests pass after: PASS
+- [x] Coverage: 95% (maintained)
+- [x] Complexity: 10 → 7
+- [x] Commit: `git commit -m "refactor: extract collectTimestamps helper"`
+
+### Post-Refactoring
+- [x] All tests pass: PASS
+- [x] Coverage: 85% → 95% (+10%)
+- [x] Complexity: 10 → 6 (-40%)
+- [x] Duplication: 0 (no change)
+- [x] Documentation: Added GoDoc to calculateSequenceTimeSpan
+- [x] 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)