bp-refactor

Safe Refactoring Protocol

Never refactor without locking down existing behavior first. This follows Boris Cherny's 4-step legacy refactoring protocol.

Steps

1. Write characterization tests FIRST -- Before touching any logic, write tests that lock down the current behavior. Even if the current behavior is buggy, test it as-is. For large refactors (50k+ LOC), Boris recommends spending the first 4 days purely on characterization tests.

2. Check CLAUDE.md for load-bearing walls -- Verify that the area to be refactored is not protected. If it is, stop and discuss with the developer.

3. Plan atomic chunks -- Split the refactor into independently landable pieces:

   • Interfaces and types first
   • Helper functions second
   • Implementation changes last
   • Each chunk should be independently reviewable and revertable

4. Execute one chunk at a time -- Implement each chunk and run /bp-verify after each one. Never combine multiple chunks into a single change.

5. If a chunk fails -- Revert the chunk entirely and rescope. Do NOT patch on top of a failed refactoring step. Go back to the plan and try a different approach.

Anti-Patterns

• DO NOT refactor and change behavior simultaneously -- separate them
• DO NOT skip characterization tests -- they are the safety net
• DO NOT submit one giant diff -- break it into atomic, landable chunks
• DO NOT patch around failures -- revert and rescope

Quality Checks

• Characterization tests pass before AND after each chunk
• No chunk exceeds 200 lines of changes
• Existing behavior is preserved (unless intentionally changed in a separate PR)
• Load-bearing walls are respected