Quest Plan

Refactor Arc · 4 levels · populated

Level 1 · Scope the target

Name the one thing you’re refactoring and the truth you’ll check it against. Pick a single specific target — not “clean up the module,” but the actual smell: duplicated logic across three call sites, a class doing two unrelated jobs, a function whose name lies about what it does. Write down its current observable behavior — inputs, outputs, side effects, and the edge cases that already work — before you touch anything. This baseline is what every later stage gets checked against, so be concrete: exact function signatures, exact test names, exact edge cases. When the target and the baseline are both written down, run quest_level complete.

Level 2 · Refactor in stages

Move toward the target shape in the smallest steps that could each stand alone as a commit. Each stage should be independently reviewable and independently revertible. Run the tests after every stage before starting the next one — never stack an unverified structural change on top of another. A stage that changes both structure and behavior at once is two changes pretending to be one; split it. If a stage reveals the target shape was wrong, that’s fine — update level 1’s plan and say so, don’t silently drift. When the code is in its target shape and every stage landed clean, run quest_level complete.

Level 3 · Verify no behavior change

Prove the refactor changed nothing a caller could observe. Check every stage’s result against the level-1 baseline: same tests pass, same edge cases produce the same outputs, no default silently changed, no error path silently swallowed or exposed differently. If you find a behavior difference, decide deliberately whether it’s an intentional improvement worth calling out on its own, or a regression to fix before continuing — never let one slide through disguised as “basically the same.” When every stage is confirmed behavior-identical (or its deviations are explicitly flagged), run quest_level complete.

Level 4 · Clean up

Leave no trace of the old shape lying around. Remove dead code the refactor made obsolete — old code paths, now-unused feature flags, TODOs the refactor actually resolved. Update comments and docs that still describe the pre-refactor structure; a comment describing code that no longer exists is worse than no comment. Write a short note for the next reader: what changed, why, and where the old approach used to live in case someone goes looking for it. When the tree is clean and the note is written, run quest_level complete.