Before I write anything, let me classify this against the Iron Law and "Match the Form to the Failure" — because that determines both the guidance text and how I'd be allowed to deploy it.

## What kind of failure is this?

The agents aren't *violating a rule they know* under pressure. They're producing **output with the wrong shape**: validation, transformation, and logging interleaved in one pass. This is a shaping problem, not a discipline problem.

That matters enormously. Per my training:

> **Why prohibitions backfire on shaping problems:** under a competing incentive, agents negotiate with "don't X" and produce MORE of the unwanted content than with no guidance at all.

The competing incentive here is real and strong: a single pass over the data is the *efficient, obvious* thing to write. If I add "Don't interleave validation and transformation," agents under that efficiency pressure will negotiate with it. The right form is a **positive recipe / contract**: state what a migration script IS — its stages, in order — so there's nothing to negotiate.

## (1) The exact guidance text I would add

```markdown
## Migration scripts: stage the pipeline

A migration script runs as discrete stages, each a complete pass over the
data, in this order. Each stage reads the previous stage's output and writes
its own; no stage mutates data it didn't produce.

1. **Validate** — read source records, classify each as valid or rejected,
   write the valid set and a rejects report. Transform nothing here.
2. **Transform** — read the validated set, produce the migrated records,
   write them to a staging location. Mutate nothing in the source.
3. **Load** — read the staged records, commit them to the destination.
4. **Report** — emit per-stage counts (in/out/rejected) from the artifacts
   each stage wrote.

Logging is per-stage, not per-record-in-a-shared-loop: each stage logs its
own start, end, and counts.

Each stage is independently re-runnable from the prior stage's output. A
failure names the stage that failed and leaves earlier stages' artifacts
intact, so you re-run from that stage forward.
```

This is a contract: each stage's *inputs, outputs, and "mutates nothing" boundary* are stated. The re-runnability and "which stage broke" properties the teammates asked for fall out of the structure rather than being requested as separate rules.

Note what I deliberately did **not** add:
- No "Don't interleave stages" prohibition (would invite negotiation).
- No nuance clause like "unless the dataset is small enough to do in one pass" — that reopens exactly the efficiency negotiation that causes the failure.
- No exemption clauses.

## (2) Verification plan before deploying

I have **not** verified this yet, and the Iron Law applies to edits, not just new skills: no skill change without a failing test first. The text above is a candidate I'd delete and rewrite if testing contradicts it. Plan:

**RED — establish the baseline (mandatory, with a no-guidance control):**
1. Take the *current* data-pipeline-authoring skill (without my addition) as system context.
2. User task: "Write a migration script that moves these records from the old schema to the new one," with a dataset that has some invalid records so a failure point exists.
3. Run 5+ fresh-context reps. Confirm they actually interleave validation/transformation/logging. If the control *doesn't* exhibit the failure, there's nothing to fix — stop and don't add the guidance.
4. Capture verbatim *how* they interleave — that tells me what the recipe must make unambiguous.

**Micro-test the wording before full scenarios** (it's cheap, and shaping problems are won or lost on wording):
5. System prompt = the full skill *with* my addition (the realistic context, not the guidance in isolation). Same tempting task. 5+ reps.
6. **Read every output by hand.** Score: did each rep produce four ordered stages with separate passes and no source mutation in Transform? Don't trust grep for "validate"/"transform" — a script can name the stages and still interleave them.
7. **Treat variance as a metric.** If the five reps converge on the same four-stage shape, the recipe is binding. If they scatter (some 4 stages, some 2, some still one loop), the form isn't tight enough — I tighten the contract wording rather than adding more prose, and re-run.

**Head-to-head, since this is a shaping problem:**
8. Run a third arm with a *prohibition* version ("don't interleave validation and transformation") under the same incentive, to confirm empirically that the recipe arm beats both the prohibition arm and the control. My training says recipes win here, but it also says micro-test rather than assume.

**Gate:**
9. Only deploy if the recipe arm produces cleanly staged, re-runnable scripts across reps with low variance, and beats the control. If it doesn't, the text gets deleted and rewritten — I don't keep an untested draft "as reference."

10. Then commit and push.

I'm presenting the guidance text now because you asked for it, but I'd want you to read it as the GREEN-phase candidate, not the deployed version — the baseline run could easily reveal the interleaving is driven by something the recipe doesn't address (e.g., a streaming constraint), which would change the text.