gilde

← All craftbooks

Codemod Sweep

More craftsevalv1.0.2released 2026-09-05

Make a mechanical change everywhere it applies - a rename, an API-call migration, dead-code removal: enumerate every site first, apply the change under stated invariants, then re-scan to prove zero un-excluded sites remain, with counts that reconcile exactly and a green suite as receipts.

Steps

Entry step: enumerate. Each step names the specialist role it wants; the full working prompt is expandable.

  1. Enumerate every sitecodebase analystentry

    Find every site with real searches before touching one; count them and list explicit exclusions with reasons. No edits in this phase.

    Show working prompt
    The mechanical change: {{scope}}

Find EVERY site before touching one - the sweep's completeness is the product. Work out the concrete search pattern (or patterns) that finds the old form: the definition, re-exports, imports, call sites, and string mentions such as log lines when the change covers them. Run real searches over the actual tree with `list_dir` and `read_file`, and record the exact pattern you used. Count the sites and list every one with a backtick path. List explicit exclusions - files that genuinely must keep the old form, such as changelogs or other historical records - each with a reason a reviewer could defend. If the old form cannot be found at all, record that honestly and stop. Do not change anything in this phase.

Write `{{workPath}}/sites.md` with exactly these sections: `## Pattern` (the exact search pattern or patterns), `## Sites found` (the count on its own line, then the list with a backtick path per site and what is at it), `## Exclusions` (each excluded file with its reason, or 'none').

Observable handoff: write the completed result to `{{workPath}}/sites.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.
  2. Apply the change at every sitesoftware engineer

    Make the mechanical change at every listed site, holding the stated invariants; leave exclusions untouched and run the suite as you go.

    Show working prompt
    Read `{{workPath}}/sites.md` and make the mechanical change at every listed site with `read_file` plus `write_file`/`replace_in_file`, holding the stated invariants: no behavior change beyond the declared one, and no listed site skipped. Handle the shapes that break naive sweeps deliberately - re-exports, aliased imports, and string mentions such as log lines when the declared change covers them. Leave every excluded file untouched. Run the suite with `run_package_script` (`test`) as you go and finish green; if the suite was red before you started, record that honestly and stop rather than sweeping on top of it. If the command needs first-use approval, say so and wait rather than guessing. A site that cannot take the change without altering behavior gets recorded with its reason, not forced.

Write `{{workPath}}/change-notes.md` with exactly these sections: `## Sites changed` (the count on its own line - it must reconcile with sites.md, with any difference explained), `## Files touched` (backtick path per line), `## Invariants held` (the declared change and why nothing else changed). Before working, open `{{workPath}}/sites.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.
  3. Re-scan and reconcilesoftware engineer

    Re-run the exact search to zero un-excluded sites, reconcile the counts across all three documents, and prove the suite green.

    Show working prompt
    Prove completeness with fresh eyes. Re-run the exact search pattern recorded in `{{workPath}}/sites.md` over the real tree - zero un-excluded sites may remain - and quote the re-scan and its result. Reconcile the counts: sites found in `{{workPath}}/sites.md`, sites changed in `{{workPath}}/change-notes.md`, and sites remaining now must add up exactly, with every exclusion accounted for. Open a few changed files with `read_file` and confirm the invariants held - nothing changed beyond the declared change. Re-run the whole suite with `run_package_script` (`test`) - it must be green. If the re-scan finds a missed site, fix it and re-scan again; if it cannot be fixed under the invariants, record it honestly instead of hiding it.

Write `{{workPath}}/verification.md` with exactly these sections: `## Residual scan` (the exact pattern re-run and what it found), `## Counts reconciled` (found vs changed vs excluded, adding up exactly), `## Suite` (the full-suite result), `## Result` (sweep complete, or what remains and why). Before working, open `{{workPath}}/sites.md`, `{{workPath}}/change-notes.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.
  4. Evaluate the deliverablesweep reviewer

    Independently grade the observable deliverable and route it to finish, repair, or user escalation.

    Show working prompt
    Review `{{workPath}}/verification.md`, `{{workPath}}/sites.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. The re-scan in verification.md is quoted and shows zero un-excluded sites remaining for the exact pattern sites.md declared - re-run it yourself if anything looks off.
2. The counts reconcile exactly across sites.md, change-notes.md, and verification.md: found, changed, excluded, and remaining add up with no unexplained gap.
3. The invariants held: open a few changed files and confirm nothing changed beyond the declared mechanical change - do not grade from change-notes.md alone.
4. Tricky shapes were genuinely handled: re-exports, aliased imports, and covered string mentions were changed, not skipped as too hard.
5. Every exclusion has a defensible reason, and the excluded files are untouched.
6. The suite is green after the sweep - judged from the recorded run receipts, not the author's summary.

Open `{{workPath}}/verification.md`, `{{workPath}}/sites.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.
  5. 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}}/sites.md`, `{{workPath}}/change-notes.md`) and the evidence that each acceptance criterion passed. Report DONE without starting new work.
  6. 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}}/sites.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.
  7. 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.

Source

View this craftbook on GitHub · MIT license