Refactor Loop

/goal Refactor the target module in small steps, keeping external behavior identical and the test suite green after each step.
 
Task type: Custom
Target tool: Claude Code
 
Work toward this goal until all validation checks pass or the stop rule is reached.
 
Design hypothesis:
This refactor loop can produce a safer result if the scope stays narrow, validation is explicit, and a checker can reject shortcut work.
 
Smallest useful run:
Run one bounded pass on the newest relevant signal before expanding scope or adding a schedule.
 
Loop cycle:
1. Discovery — Read the latest signal for this template before acting: CI output, issue detail, review comment, dataset report, or content brief.
2. Handoff — Hand the work to one agent in an isolated branch, worktree, or clearly scoped session. Keep final approval with a human.
3. Verification — Use an independent review pass to confirm the result, inspect the diff or artifact, and reject shortcut work.
4. Persistence — Save a short run note with the signal reviewed, actions taken, validation result, and next recommended step.
5. Scheduling — Run manually until the loop is reliable; only then consider a scheduled or event-triggered run.
 
Context:
Behavior must not change. Run the tests after each step. Prefer many small, reversible changes over one large rewrite — for example, splitting a large file into focused modules until each is under a size budget.
 
Validation:
Full test suite passes after each step
Public API and external behavior are unchanged
No file exceeds the agreed size budget
Type checks pass
 
Validation evidence:
Record the original signal, checks run, final result, changed files or artifacts, and any checker rejection.
 
Independent checker:
Use an independent review pass to confirm the result, inspect the diff or artifact, and reject shortcut work.
 
Boundaries:
Do not change external behavior or public APIs
Do not mix in new features
Do not delete tests
Do not refactor unrelated modules
 
Stop rule:
Stop when the refactor goal is met and tests are green, or after 5 failed steps. With Claude /goal, bound it by adding “or stop after N turns” to the condition.
Maximum iterations: 6
 
Budget:
Example only: stop before exceeding the agreed per-run token budget.
 
Human approval:
Required before merge, deploy, delete, purchase, or external communication.
 
Fallback:
If a step breaks behavior, revert it, summarize what broke, and recommend a smaller step or a human decision.
 
Loop Validation Log:
- Hypothesis: This refactor loop can produce a safer result if the scope stays narrow, validation is explicit, and a checker can reject shortcut work.
- Smallest useful run: Run one bounded pass on the newest relevant signal before expanding scope or adding a schedule.
- Expected evidence: Record the original signal, checks run, final result, changed files or artifacts, and any checker rejection.
- Actual evidence: [fill in after the run]
- Passed? [yes / no / partial]
- Feedback: After the run, note what the loop learned, what failed, and what should change before the next pass.
- Next step: [stop / adjust the loop / run the next pass]
 
Do not delete tests, bypass checks, or modify unrelated files just to satisfy the validation condition. If blocked, stop and summarize the blocker, attempted fixes, and recommended next action.