Behavior-Preserving Refactor
Restructure code without changing what it does, with proof at every stage: a green suite recorded before anything moves (characterization tests pinned first when coverage is thin), small reversible stages that keep the tests green, a re-measured structure target, and an enforced independent review.
Steps
Entry step: baseline. Each step names the specialist role it wants; the full working prompt is expandable.
- Capture the baselinesoftware engineerentry
Record the current truth before changing anything: suite green, structural measurements, and the guardrail — with characterization tests added first where coverage is thin.
Show working prompt
The refactor scope: {{scope}} Capture the current truth before changing anything — measure BEFORE, so the improvement can be proven later with the same method. Read the involved source and find how this project runs its tests (`list_package_scripts`, then read the existing test layout). Run the suite with `run_package_script` (`test`) and confirm it is GREEN before any restructuring; if it is already red, stop and report that honestly instead of refactoring on a broken base. If the command needs first-use approval, say so and wait rather than guessing. Where the code you are about to restructure lacks tests, write characterization tests FIRST: tests that pin the CURRENT behavior — bugs and quirks included — in the project's real test layout and style. They are the guardrail. Run them and record that they pass against today's code; do not fix anything they reveal. Then record the structural measurements this refactor targets, as numbers gathered by a stated method: duplicated blocks and where each copy lives, function lengths, file sizes, tangled responsibilities — counted, not adjectived. Write `{{workPath}}/baseline.md` with exactly these sections: `## Current behavior` (what the code does today and which tests pin it, including any characterization tests you just added), `## Measurements` (the structural numbers and the exact method used to gather them), `## Guardrail` (what must not change: public API, observable behavior, and the suite staying green). Cite the real files involved with backtick paths. Observable handoff: write the completed result to `{{workPath}}/baseline.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections. - Plan reversible stagessoftware architect
Design the target structure and an ordered sequence of small stages, each individually reversible and each leaving the tree working. No source edits.
Show working prompt
Read `{{workPath}}/baseline.md`, then design the restructure as a sequence of small stages. State the target structure concretely: what exists after the refactor that does not exist now, and what disappears. Break the work into ordered stages where EACH stage is individually reversible and leaves the tree working with the suite green — extract this function, move that block behind a seam, collapse the duplicate — never a big-bang rewrite. Name the files each stage touches. State the acceptance criteria: the measured target from the baseline moving (with the figures it should reach), the suite green after every stage, and the public API unchanged unless you explicitly declare a break here and say why. Do not edit any source in this phase. Write `{{workPath}}/plan.md` with exactly these sections: `## Target` (the end structure), `## Stages` (numbered, each reversible, each naming its files), `## Acceptance criteria`. Cite the real files with backtick paths. Before working, open `{{workPath}}/baseline.md` with `read_artifact`. Observable handoff: write the completed result to `{{workPath}}/plan.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections. - Restructure stage by stagesoftware engineer
Execute the planned stages at the real sites, keeping the suite green between stages.
Show working prompt
Read `{{workPath}}/plan.md` and `{{workPath}}/baseline.md`, then execute the stages in order at the REAL sites — edit the actual files with `read_file` plus `write_file`/`replace_in_file`; there is no prescribed output path for source changes and never a scratch copy. After EACH stage, run the suite with `run_package_script` (`test`) and confirm it is still green before starting the next; a stage that goes red gets reverted or narrowed until green, not stacked on. Keep behavior identical: no fixes or features smuggled in under cover of the restructure — if you find a genuine bug, record it in your notes for the user instead of silently changing behavior the tests pin. Keep the characterization tests from the baseline; they ride along as permanent guards. Write `{{workPath}}/change-notes.md` with exactly these sections: `## Stages executed` (each stage, in order, with its suite-green confirmation), `## Files touched` (backtick path per line), `## Deviations from plan` (anything done differently than plan.md and why; write `none` honestly when there are none). Before working, open `{{workPath}}/baseline.md`, `{{workPath}}/plan.md` with `read_artifact`. Observable handoff: write the completed result to `{{workPath}}/change-notes.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections. - Re-measure and verifysoftware engineer
Re-measure with the same method as the baseline, quote both figures, and record the suite green.
Show working prompt
Prove the refactor with fresh eyes. Read `{{workPath}}/baseline.md` and re-measure the SAME structural numbers with the SAME method it records — the comparison is meaningless if the method moved. Quote the before figure from the baseline and the after figure side by side. Then run the whole suite with `run_package_script` (`test`) and record the green result. Check the guardrail: exports, signatures, and observable behavior unchanged unless plan.md declared a break. Anything you could not actually re-run gets labeled unverified, never claimed. Write `{{workPath}}/verification.md` with exactly these sections: `## Before / after` (each baseline measurement quoted next to its re-measured value, same method), `## Suite` (the full-suite result from the real run), `## Result` (behavior preserved and target moved, or what remains unverified and why). Before working, open `{{workPath}}/baseline.md` with `read_artifact`. Observable handoff: write the completed result to `{{workPath}}/verification.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections. - Evaluate the deliverablerefactoring reviewer
Independently grade the observable deliverable and route it to finish, repair, or user escalation.
Show working prompt
Review `{{workPath}}/verification.md`, `{{workPath}}/baseline.md`, `{{workPath}}/plan.md`, `{{workPath}}/change-notes.md` against every criterion below. Inspect the underlying evidence files named by the workflow; do not grade from the author's summary alone. 1. baseline.md records a genuinely green suite from a real run receipt before any restructuring, and pins the guardrail — with characterization tests written first (pinning current behavior, bugs included) wherever the touched area lacked coverage. 2. Observable behavior unchanged (or changed only as the plan declared): public API and outputs held, and the pinning tests still pass unmodified — open the touched files and the tests; do not grade from change-notes.md alone. 3. The measured target moved against the recorded baseline using the same method: verification.md quotes both figures side by side, and the duplication/structure improvement is visible in the real files, not just claimed. 4. No stage left the suite red (receipts, not claims): the recorded runs show green between stages and green at the end. 5. Every stage in change-notes.md matches a plan.md stage or an honestly recorded deviation, and every touched file it names exists. 6. The public API is unchanged unless plan.md explicitly declared a break, and no fix or feature was smuggled in under cover of the restructure. Open `{{workPath}}/verification.md`, `{{workPath}}/baseline.md`, `{{workPath}}/plan.md`, `{{workPath}}/change-notes.md` with `read_artifact`. Write the evidence-backed review to `{{workPath}}/review.md` in the artifacts drawer with `write_artifact`. List the findings as a markdown table with columns `| Severity | File | Line | Problem | Fix |` (severities: critical/major/minor/nit; empty table only on PASS). Give each criterion a PASS or FAIL with a concrete path, excerpt, measurement, or observed behavior. End with exactly `Verdict: PASS` or `Verdict: REVISE`. The gate ENFORCES the verdict: a well-formed REVISE is rejected and routed back to `repair` automatically, carrying your findings — so list every finding in the table with a concrete fix. On PASS, `advance_task_step` to `finish`. Never write PASS while a criterion is unmet. - Finishproject lead
All deterministic and reviewer criteria passed.
Show working prompt
The independent review passed. Read `{{workPath}}/review.md` with `read_artifact`, then use `write_task_note` to record a concise DONE summary with the final deliverable paths (`{{workPath}}/verification.md`, `{{workPath}}/baseline.md`, `{{workPath}}/plan.md`, `{{workPath}}/change-notes.md`) and the evidence that each acceptance criterion passed. Report DONE without starting new work. - Repair the deliverablesoftware engineer
Fix only the concrete gaps from the latest independent review.
Show working prompt
Read `{{workPath}}/review.md` with `read_artifact` and repair every failed criterion in `{{workPath}}/verification.md`, `{{workPath}}/baseline.md`, `{{workPath}}/plan.md`, `{{workPath}}/change-notes.md`. Make changes on each file's declared surface (`write_artifact` for artifact inputs, `write_file` for workspace inputs), not in task notes or a reply. Preserve evidence that already passed. Re-run or re-check anything the reviewer found unproven. Ensure `{{workPath}}/verification.md` is genuinely updated this turn so the repair is observable, then hand it back for independent evaluation. - Escalate unresolved concernsproject lead
The bounded repair loop ended without a defensible pass.
Show working prompt
The deliverable did not pass after 3 review rounds. Do not claim success. Read `{{workPath}}/review.md` with `read_artifact`, then use `write_task_note` to record DONE_WITH_CONCERNS: the unmet criteria, what was attempted, the affected paths, and the smallest user decision or missing input needed to continue.
Triggers
Phrases that suggest this craftbook to a crew.
- refactor this module
- clean up the code
- improve code structure
- behavior-preserving refactor
- reduce duplication
Source
View this craftbook on GitHub · MIT license