I'll resist the pull to just write good-sounding guidance. The Iron Law applies to edits too: no skill change without a failing test first. But I can still reason about the *form* the guidance should take, and that's where I'll start—because the form determines whether the guidance will work at all.

## First: classify the failure

The complaint is "scripts interleave validation, transformation, and logging in a single pass." Agents are *producing output with the wrong shape*. They aren't knowingly violating a rule under pressure—they just write the migration as one loop because nobody told them the output has distinct stages.

Per **Match the Form to the Failure**, this is a "wrong shape" problem, not a discipline problem. The right form is a **positive recipe/contract** stating what a migration script IS—its stages, in order. A prohibition list ("don't interleave validation with transformation") would be the wrong form and may backfire, producing *more* tangled scripts under the competing incentive to "just make the migration work."

So the guidance below is a recipe, not a set of prohibitions. **But I haven't tested it yet**—the text below is a candidate, and per the Iron Law I won't deploy it until the verification plan passes. If the baseline shows agents already stage correctly, I delete it entirely.

## (1) Candidate guidance text

```markdown
## Migration Script Structure

A migration script runs as discrete stages, each a complete pass that
produces a checkpointed artifact before the next stage begins. Never
fold multiple stages into one loop over the data.

The stages, in order:

1. **Extract** — read source records into a staging location. Output:
   raw staged records + a count.
2. **Validate** — read staged records, write each to either a
   `valid` or `rejected` set with a reason. Output: valid set,
   rejected set, validation report. Performs no transformation.
3. **Transform** — read the valid set, write transformed records to a
   `transformed` set. Output: transformed set. Reads only validated
   input; never re-validates.
4. **Load** — write the transformed set to the destination. Output:
   load report with success/failure counts.

Each stage:
- Reads its input from the previous stage's checkpointed output, not
  from a shared in-memory pass.
- Is independently re-runnable: re-running a stage on its input
  produces the same result and overwrites only its own output.
- Logs to a stage-scoped log (stage name + record id), so a failure
  report names the stage that broke.

A failure halts the pipeline at the failing stage. Re-run resumes from
that stage's input checkpoint—earlier stages are not repeated.
```

## (2) Verification plan before deploying

I will not add this text until it survives the RED-GREEN cycle.

**RED — establish the baseline (mandatory).**
- Write 2–3 realistic migration tasks (e.g., "migrate the users table to the new schema, dropping records with malformed emails"). Each tempts a single-pass loop because that's the obvious quick path.
- Run each task with a fresh subagent using the **current** skill (no new guidance). Capture verbatim whether they interleave stages, omit checkpoints, and whether their logging identifies the failing stage.
- **If the baseline already produces staged scripts, stop and delete the guidance.** No failing test, no edit.

**Micro-test the wording (cheap iteration before full scenarios).**
- System prompt = the full skill with this section inserted (realistic context, not the snippet alone). User message = a migration task.
- Include a **no-guidance control** arm every run.
- 5+ reps per arm. Read every output manually—an agent can echo "Extract/Validate/Transform/Load" headers while still writing one fused loop, which an automated keyword count would falsely score as a pass.
- Check the metric of **variance**: if the 5 reps converge on the same four-stage, checkpointed shape, the recipe is binding. Five different interpretations means the form is too loose—tighten it (e.g., make the checkpoint artifact a named required output) rather than adding prose.

**GREEN — confirm the fix.**
- Re-run the original RED scenarios with the guidance present. Success = each stage is a separate pass reading a checkpointed input, logs are stage-scoped, and the agent can state which stage a failure occurred in and re-run from it.

**Guard against form regressions.**
- Verify I haven't smuggled in a nuance clause ("don't split stages unless performance matters")—that reopens the negotiation. Any real exception (e.g., streaming-only sources that can't checkpoint) gets expressed as its own conditional on an observable predicate, not as an exemption to the recipe.

**Deploy only after GREEN passes**, then commit.