gilde

← All craftbooks

Schema / Type Migration

Build: software and codeevalv2.0.2released 2026-09-05workflow: build-loop

Migrate a schema or data shape with the expand/contract discipline: reads accept both shapes while the data moves, the old shape is dropped only after every record is transformed, and real suite runs between stages prove no record was ever stranded.

Steps

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

  1. Plan the expand/contract migrationmigration plannerentry

    Document the current and target shapes from the real files and stage the work as expand, migrate, contract - with per-stage data safety and rollback.

    Show working prompt
    The migration: {{scope}}

Plan from the REAL files before changing anything. Read the actual schema definitions and the actual data files, and find every accessor that touches the current shape with real searches over the tree - never from memory. Document the current shape and the exact target shape with field names and types taken from those files. Then lay the work out as expand/contract stages - the data must stay readable through every stage: first EXPAND (readers accept both the old and the new shape), then MIGRATE (transform the stored data to the new shape), then CONTRACT (drop the old shape and retire the dual-read). For each stage, state what keeps every existing record readable while that stage is in flight, and the concrete rollback if it goes wrong. If the current shape cannot be determined from the real files, record what is missing honestly and stop.

Write `{{workPath}}/migration-plan.md` with exactly these sections: `## Current shape` (from the real files, cited with backtick paths), `## Target shape` (exact fields and types), `## Stages` (expand, migrate, contract - what each touches, in order), `## Data safety` (why no record becomes unreadable at any stage), `## Rollback per stage`.

Observable handoff: write the completed result to `{{workPath}}/migration-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.
  2. Execute the stagessoftware engineer

    Apply expand, migrate, contract at the real sites with the suite run between stages; reads accept both shapes until the plan retires the dual-read.

    Show working prompt
    Read `{{workPath}}/migration-plan.md` and execute its stages in order at the real sites it names - the schema definition, the accessors, and the data transform - using `read_file` plus `write_file`/`replace_in_file`. Run the suite with `run_package_script` (`test`) between stages: expand must be green before the data moves, and the data must be fully transformed before contract drops the old shape. During expand, reads accept BOTH shapes, and the plan's contract stage says exactly when that dual-read retires - do not leave it behind as permanent fallback code, and do not remove it before the data has moved. Transform the stored data with a real, repeatable step (a script you ran, or an explicit recorded edit), never by retyping records from memory. If the command needs first-use approval, say so and wait rather than guessing. If a stage cannot keep the suite green, return the tree to the last green stage and record what blocked you honestly.

Write `{{workPath}}/change-notes.md` with exactly these sections: `## Stages executed` (each stage with its suite result), `## Files touched` (backtick path per line), `## Data transformed` (which records moved, how, and how you know none were lost), `## Deviations` (where execution departed from the plan and why, or 'none'). Before working, open `{{workPath}}/migration-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.
  3. Prove no record was strandedsoftware engineer

    Check every record is in the target shape with values intact, the old shape is gone where contract says, and the whole suite is green.

    Show working prompt
    Prove the migration with fresh eyes. Open the migrated data with `read_file` and check every record is in the target shape and none was lost - count records against the pre-migration state recorded in `{{workPath}}/change-notes.md`, and spot-check that values survived exactly. Search the real code for leftover reads of the old shape: the old field access must be gone exactly where the plan's contract stage says it should be gone. Re-run the whole suite with `run_package_script` (`test`) - it must be green. Anything you could not actually run or open gets labeled unverified, never claimed.

Write `{{workPath}}/verification.md` with exactly these sections: `## Old shape check` (the search you ran for leftover old-shape reads and what it found), `## Data integrity` (record counts and the spot-checked values), `## Suite` (the full-suite result), `## Result` (migrated with no record stranded, or what remains unverified and why). Before working, open `{{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 deliverablemigration reviewer

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

    Show working prompt
    Review `{{workPath}}/verification.md`, `{{workPath}}/migration-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. Every record stayed readable at every stage: the plan's expand stage genuinely accepted both shapes, and the recorded stage order never left data unreadable in between.
2. The contract stage landed only after the data moved: change-notes.md shows the transform completed (with a green suite) before the old shape was dropped.
3. Accessors changed at real sites: every path under Files touched exists and the change there matches the plan - open the touched files; do not grade from change-notes.md alone.
4. Data integrity is proven, not asserted: verification.md counts records against the pre-migration state and spot-checks that values survived exactly.
5. No old-shape read is left outside what the plan deliberately retains: the verification search is quoted and its result matches the contract stage.
6. Rollback per stage is genuine: each stage names a concrete restore path a person could actually follow, not a vague promise.

Open `{{workPath}}/verification.md`, `{{workPath}}/migration-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.
  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}}/migration-plan.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}}/migration-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.
  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