Before I write anything, let me apply the Iron Law and the "Match the Form to the Failure" classification, because both shape what I produce.

## Classifying the failure first

The reported symptom is: scripts **interleave validation, transformation, and logging in a single pass**. Agents aren't violating a rule they know under pressure — they're producing output with the **wrong shape**. That's a shaping failure, not a discipline failure.

Per Match the Form to the Failure, the right form is a **positive recipe/contract** that states what a migration script IS (its stages, in order), not a prohibition list like "don't interleave validation with transformation." Prohibitions backfire on shaping problems — agents negotiate with them. So the guidance below is a recipe, with structural slots, not a "never do X" list.

I am **not** writing this guidance and shipping it. The Iron Law applies to edits too: no skill change without a failing test first. So the honest answer has two parts, and the verification plan is the part that gates whether the text below survives contact with reality. The text below is a *candidate* to test, not a finished addition.

---

## (1) Candidate guidance text

```markdown
## Staged Migration Scripts

A migration script is three separate passes over the data, in this order.
Each pass reads the output of the previous one and writes a durable artifact
before the next begins:

1. **Validate** — read source records, check every invariant, write a
   validation report (passed IDs, failed IDs + reason). Transform nothing.
2. **Transform** — read only the passed IDs from stage 1, produce the
   migrated records, write them to a staging location. Re-check nothing
   that stage 1 already decided.
3. **Commit** — move staged records into the destination. No transformation
   logic here.

**Required structure:** each stage is a separate function with its own
entry point, takes the previous stage's artifact as input, and writes its
artifact to disk before returning. A failed run names the stage that
failed and leaves all earlier artifacts intact.

**Logging is not a stage.** Each stage emits its own structured log
(stage name, counts in/out, failures). Logging never happens inline with
transform logic — it reports on a stage from outside it.

**Re-running:** because each stage's output is durable, a failed migration
re-runs from the failed stage using the prior artifact, without redoing
earlier work.
```

Notes on form choices:
- "A migration script is three separate passes... in this order" is the contract — output matches the stated shape or it doesn't.
- "Required structure" is a **structural slot** (separate function + artifact in/out), per the row for omitted-element failures — agents fill in a shape rather than remember a reminder.
- "Logging is not a stage" / "Logging never happens inline" — I'm wary here. This is the one spot that drifts toward prohibition. I'm flagging it as the highest-risk wording to micro-test, because an exemption/negation about logging may suppress logging entirely (the "exemption clauses don't scope" trap).
- No nuance clauses ("unless the migration is small...") — those reopen negotiation.

---

## (2) Verification plan before deploying

**RED — baseline (mandatory, do this first):**
1. Take a realistic data-migration task that tempts interleaving (e.g. "migrate user records, dropping invalid ones, into the new schema").
2. Run it through a fresh agent **with the current skill and no new guidance** — the no-guidance control. 5+ reps.
3. Confirm the failure actually reproduces: do they interleave validate/transform/log in one pass? Read every transcript manually. **If the control doesn't exhibit interleaving, stop — there's nothing to fix and I don't add the guidance.**
4. Record verbatim how interleaving shows up (shared loop? logging mid-transform? no durable intermediate artifact?). This tells me whether my three named stages are the right cut.

**Micro-test the wording (before full scenarios):**
5. Same task, system prompt = full skill **with** candidate guidance, 5+ reps. Compare against the control.
6. Specifically watch the logging clause: does "logging is not a stage" cause agents to *drop* logging rather than separate it? If so, restructure (e.g. make per-stage logging a structural slot inside each stage's contract) rather than negate.
7. **Variance is the metric.** If five reps converge on three separate functions with artifacts between them, the recipe is binding. If I get five different structures, the form is too loose — tighten before adding words.

**GREEN / REFACTOR:**
8. Run full pressure scenarios (time pressure, "just a small migration") to catch collapse-back-to-one-pass under load.
9. Any new rationalization → address structurally, re-test until convergent.

**Only after the control reproduces the failure and the guidance produces convergent, correctly-staged output do I commit and deploy.** If RED shows no failure, or GREEN doesn't converge, the candidate text above gets deleted, not kept "for reference."