TDD Refactor Guard

A safety gate that runs before any AI-assisted refactoring. Ensures tests exist to catch regressions. If coverage is insufficient, generates characterization tests first.

When This Skill Activates

Use this skill when the user:

• Says "refactor this" or "clean this up"
• Wants AI to "restructure" or "reorganize" code
• Asks to "extract", "inline", "rename", or "simplify" existing code
• Plans to migrate between patterns (e.g., MVC → MVVM, CoreData → SwiftData)
• Wants AI to "improve" or "modernize" existing code

Why This Guard Exists

Without guard:               With guard:
"Claude, refactor this"      "Claude, refactor this"
  → AI rewrites code           → Guard checks for tests
  → Something breaks           → Tests missing → generate them
  → You don't know what        → Tests pass → proceed with refactor
  → Debugging nightmare         → Tests fail → exact regression found

Process

Step 1: Identify Scope

What code is being refactored?

Ask user: "Which files/classes are you planning to refactor?"

Or detect from context:

Glob: [files mentioned in conversation]
Read: each file to understand scope

Determine:

• Files involved
• Public API surface (methods, properties)
• Dependencies (what calls this code, what it calls)
• Side effects (network, disk, notifications, UI updates)

Step 2: Check Existing Test Coverage

Grep: "class.*Tests.*XCTestCase|@Suite.*Tests|struct.*Tests" in test targets
Grep: "@Test|func test" that reference the classes being refactored

Coverage Assessment

Step 3: Evaluate Test Quality

Even if tests exist, check quality:

swift
1// ❌ Low-quality test — doesn't actually verify behavior
2@Test("test items")
3func testItems() {
4    let vm = ViewModel()
5    vm.loadItems()
6    #expect(true)  // Always passes, tests nothing
7}
8
9// ❌ Tests implementation, not behavior
10@Test("calls repository")
11func testCallsRepo() {
12    let vm = ViewModel()
13    vm.loadItems()
14    #expect(mockRepo.fetchCallCount == 1)  // Brittle
15}
16
17// ✅ Tests observable behavior
18@Test("loads items into published array")
19func testLoadsItems() async {
20    let vm = ViewModel(repo: MockRepo(items: [.sample]))
21    await vm.loadItems()
22    #expect(vm.items.count == 1)
23    #expect(vm.items.first?.title == "Sample")
24}

Quality checklist:

• Tests verify outputs/state, not implementation details
• Both happy path and error paths covered
• Edge cases (empty, nil, boundary) tested
• Async behavior properly awaited
• No #expect(true) or always-passing assertions

Step 4: Generate Missing Tests

If coverage is insufficient, use characterization-test-generator/:

markdown
1Before refactoring [ClassName], generate characterization tests:
21. Read the source file
32. Identify all public methods
43. Generate tests that capture CURRENT behavior
54. Run and verify all pass

Step 5: Green Light / Red Light

Green Light — Proceed

markdown
1## Refactor Guard: ✅ PROCEED
2
3**Files**: ItemManager.swift, ItemRepository.swift
4**Test coverage**: Good (12 tests covering 8/9 public methods)
5**Test quality**: Adequate — tests verify behavior, not implementation
6
7Safe to refactor. Run tests after each change:
8`xcodebuild test -scheme YourApp`

Yellow Light — Needs Work

markdown
1## Refactor Guard: ⚠️ NEEDS TESTS
2
3**Files**: ItemManager.swift, ItemRepository.swift
4**Test coverage**: Partial (5 tests covering 4/9 public methods)
5**Missing coverage**:
6- `ItemManager.sort()` — no test
7- `ItemManager.filter(by:)` — no test
8- `ItemRepository.sync()` — no test
9- Error paths for `save()` and `delete()` — not tested
10
11**Action**: Generate characterization tests for uncovered methods before refactoring.
12Use `characterization-test-generator` skill.

Red Light — Stop

markdown
1## Refactor Guard: 🔴 STOP
2
3**Files**: ItemManager.swift, ItemRepository.swift
4**Test coverage**: None (0 tests found)
5
6**Action**: Do NOT refactor until characterization tests exist.
7Refactoring without tests is like surgery without monitoring —
8you won't know if you killed the patient.
9
10Run `characterization-test-generator` on:
111. ItemManager (7 public methods)
122. ItemRepository (5 public methods)
13
14Then re-run this guard.

Step 6: Post-Refactor Verification

After refactoring is complete:

bash
1# Run all tests
2xcodebuild test -scheme YourApp
3
4# Check specifically for regressions
5xcodebuild test -scheme YourApp \
6  -only-testing "YourAppTests/ItemManagerCharacterizationTests"

• All pre-existing tests still pass
• Characterization tests still pass
• No new warnings or errors
• Public API surface unchanged (unless intentionally changed)

Refactoring Safeguards

Safe Refactorings (Low Risk)

These typically don't change behavior:

• Rename variable/method/type
• Extract method/function
• Inline temporary variable
• Move method to another type (keeping same behavior)
• Extract protocol from class

Risky Refactorings (Need Good Coverage)

These can change behavior:

• Change method signature
• Reorder operations
• Replace algorithm
• Merge/split classes
• Change data structure
• Introduce async/await to sync code
• Migration between frameworks (CoreData → SwiftData)

Migration Refactorings (Need Comprehensive Coverage)

Full contract tests recommended:

• Architecture change (MVC → MVVM)
• Framework migration (UIKit → SwiftUI)
• Storage migration (UserDefaults → SwiftData)
• Concurrency model change (GCD → async/await)

Output Format

markdown
1## Refactor Guard Report
2
3**Scope**: [Files/classes to be refactored]
4**Verdict**: ✅ PROCEED / ⚠️ NEEDS TESTS / 🔴 STOP
5
6### Coverage Summary
7| Class | Public Methods | Tests | Coverage | Verdict |
8|-------|---------------|-------|----------|---------|
9| ItemManager | 9 | 12 | 89% | ✅ |
10| ItemRepository | 5 | 2 | 40% | ⚠️ |
11
12### Missing Coverage
13- [ ] `ItemRepository.sync()` — needs characterization test
14- [ ] Error path for `ItemRepository.delete()` — untested
15
16### Recommendations
171. [Action item]
182. [Action item]

References

• testing/characterization-test-generator/ — generates tests this guard may require
• testing/tdd-feature/ — for building new code during refactor
• Martin Fowler, Refactoring: Improving the Design of Existing Code