safe-refactor

This elixir works best with these skills installed:

| Skill | Purpose | If Missing |

|-------|---------|------------|

| pre-mortem | Risk assessment before starting | Falls back to built-in checklist |

| prove-it | Verification enforcement | Falls back to built-in verification |

| retrospective | Document learnings | Skipped (optional phase) |

• "Refactor this"
• "Clean up this code"
• "Rewrite this to be more..."
• "Migrate from X to Y"
• "Replace this implementation"
• Large-scale find-and-replace
• Changing shared utilities or core abstractions
• Touching code you didn't write

Phase 1: Assess Risk

If pre-mortem skill installed: Invoke it now.

If not installed, evaluate:

```markdown

What's changing:

• [ ] Files affected: [list them]
• [ ] Functions/classes modified: [list them]
• [ ] Estimated lines changed: [number]

Risk factors:

• [ ] Touches shared/core code (used by multiple features)
• [ ] Affects data persistence (database, files, cache)
• [ ] Changes public API/interfaces
• [ ] Lacks test coverage
• [ ] Written by someone else / unfamiliar code
• [ ] Production-critical path

Risk level: [Low / Medium / High / Abort]

```

GATE: Do not proceed if:

• Risk is "Abort"
• More than 3 risk factors checked AND no tests exist
• You can't list all affected files

If high risk: Consider breaking into smaller refactors.

Phase 2: Prepare

Before touching code:

1. Ensure tests exist (or write them first)

```

- [ ] Existing tests cover the behavior being preserved

- [ ] If no tests: write characterization tests NOW

```

1. Create escape hatch

```bash

git stash # or commit current state

git checkout -b refactor/[description]

```

1. Document current behavior

```

Before: [How it works now]

After: [How it should work - must be identical externally]

```

GATE: Do not proceed without:

• Tests that verify current behavior
• Clean git state (can revert easily)
• Clear before/after behavior description

Phase 3: Implement

Rules for safe refactoring:

1. One thing at a time

- Don't mix refactoring with feature changes

- Don't fix bugs you discover (note them, fix separately)

- Don't "while I'm here" other improvements

1. Small commits

```bash

# Good: multiple small commits

git commit -m "Extract helper function"

git commit -m "Rename variables for clarity"

git commit -m "Move file to new location"

# Bad: one giant commit

git commit -m "Refactor everything"

```

1. Run tests frequently

- After each logical change

- Before each commit

- If tests fail: revert and try smaller steps

1. Preserve behavior exactly

- No "improvements" to logic

- No fixing edge cases (that's a separate change)

- External behavior must be identical

Phase 4: Verify

If prove-it skill installed: Invoke it now.

If not installed:

```markdown

Automated checks:

• [ ] All existing tests pass
• [ ] No new linter errors
• [ ] Type checking passes (if applicable)

Manual verification:

• [ ] Tested the primary use case manually
• [ ] Checked one edge case
• [ ] Compared behavior before/after for critical paths

Regression check:

• [ ] git diff shows only intended changes
• [ ] No accidental behavior changes
• [ ] No debug code left in

```

GATE: Do not merge until all checks pass.

If verification fails:

```bash

git revert HEAD # or reset to before refactor

# Start over with smaller scope

```

Phase 5: Document (Optional)

If retrospective skill installed: Invoke for significant refactors.

For large refactors, capture:

• What was refactored and why
• Any tricky parts or gotchas discovered
• Patterns that emerged (potential future skills)

```markdown

Risk Assessment

• Risk level: [Low/Medium/High]
• Files affected: [count]
• Risk factors: [list]

Preparation

• [x] Tests verified/written
• [x] Branch created: refactor/[name]
• [x] Current behavior documented

Implementation

• Commits: [count]
• Approach: [brief description]

Verification

• [x] Tests pass
• [x] Manual verification complete
• [x] No regressions detected

Learnings (if significant)

[What you'd do differently]

```

• Refactor and add features in the same change
• Skip the risk assessment ("it's just a small cleanup")
• Make large changes without test coverage
• Commit all changes in one giant commit
• "Fix" bugs discovered during refactoring (note them separately)
• Proceed when tests are failing

• Assess risk before starting
• Ensure tests exist (write them if needed)
• Work on a branch with escape hatch ready
• Make small, incremental commits
• Run tests after each logical change
• Verify behavior is preserved exactly

User: "Refactor the authentication module to use the new token format"

Phase 1 - Risk Assessment:

> Refactor Risk Assessment:

> - Files affected: auth.ts, token.ts, middleware.ts, 12 test files

> - Risk factors: ✓ Core code, ✓ Production-critical, ✓ Written by someone else

> - Risk level: High

>

> Recommendation: Break into smaller refactors:

> 1. First: Add new token format support alongside old

> 2. Second: Migrate consumers one by one

> 3. Third: Remove old format

Phase 2 - Prepare:

> - [x] Existing tests cover token generation and validation

> - [x] Created branch: refactor/token-format-v2

> - [x] Documented: Old format is JWT with RS256, new format adds typ header

Phase 3 - Implement:

> Making changes incrementally...

> - Commit 1: "Add TokenV2 class with new format"

> - Commit 2: "Add feature flag for token format"

> - Commit 3: "Update token generation to use flag"

> - Tests passing after each commit ✓

Phase 4 - Verify:

> - [x] All 47 auth tests pass

> - [x] Manual test: login flow works with both formats

> - [x] Manual test: token refresh works

> - [x] git diff shows only intended changes

>

> Ready to merge.