Before I write anything, I need to apply the Iron Law: **no skill (or edit) without a failing test first.** And before I pick a *form* for the guidance, I need to classify the failure. Let me reason through this, because the way you've framed the request points toward a specific trap.

## Classifying the failure

The symptom is: agents produce migration scripts that **interleave validation, transformation, and logging in a single pass**. The desired output is cleanly *staged* scripts (distinct passes, re-runnable, with a clear failure locus).

This is **not** a discipline failure. The agents aren't knowingly skipping a rule under pressure. They're complying with the skill — they just produce output with the **wrong shape**. Per "Match the Form to the Failure," this is the "complies, but output has the wrong shape" row. The right form is a **positive recipe/contract** stating what a migration script *is* — its stages, in order. The *wrong* form is a prohibition list ("don't interleave validation and transformation," "never log mid-transform"), which measurably backfires under a competing incentive (here: "do it all in one efficient pass over the data").

So my draft is a recipe, not a set of "don't"s.

## (1) Proposed guidance text

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

A migration script IS a sequence of discrete, single-purpose stages run in
this order, each consuming the previous stage's output:

1. **Extract** — read source data into an in-memory or staged representation.
   Reads only. No transformation, no writes.
2. **Validate** — check the extracted data against the migration's
   preconditions. Produces a pass/fail result plus a list of rejected records.
   No transformation, no writes to the target.
3. **Transform** — map validated records to the target shape. Pure function of
   its input: same input, same output. No I/O to source or target.
4. **Load** — write transformed records to the target.
5. **Verify** — re-read from the target and confirm the load matches the
   transformed records.

Each stage:
- Takes the prior stage's output as input and produces a named, inspectable
  artifact (a file, table, or returned value) as output.
- Is independently re-runnable from its input artifact without rerunning
  earlier stages.
- Logs exactly one start line and one end line reporting its name, record
  counts in/out, and pass/fail. Logging lives at the stage boundary, not
  inside the per-record work.

On failure, the script reports which stage failed and stops. The artifacts
from completed stages remain on disk so the migration can be resumed from the
failed stage.
```

Notes on why it's shaped this way:
- It's a **contract**: "A migration script IS a sequence of... stages run in this order." Nothing to negotiate — the output either has these named artifacts and boundaries or it doesn't.
- The re-runnability and the failure-locus requirements (your two actual pain points) fall out structurally from "named artifact per stage" + "resume from failed stage."
- Logging is specified by **placement** ("at the stage boundary, not inside the per-record work"), which directly defeats interleaved logging without a prohibition.
- I avoided nuance/exemption clauses ("unless the dataset is small enough to do in one pass"), since appending those degrades a winning recipe. If a real one-pass exception exists, it becomes its own conditional keyed to an observable predicate — and only after testing shows it's needed.

This is a **draft**. Per the Iron Law it doesn't go in the skill until it's earned its place against a baseline.

## (2) Verification plan before deploying

**RED — baseline (mandatory, do this first):**
1. Write 3+ realistic migration tasks that tempt the single-pass shape — e.g. a task whose phrasing rewards efficiency ("migrate this table in one pass," large dataset, tight deadline framing). System prompt = the *current* data-pipeline-authoring skill verbatim, so I reproduce the real context agents are in.
2. Run each through fresh-context subagents **with the current skill but without my new guidance**, 5+ reps each.
3. Read every output and confirm the failure actually reproduces: interleaved stages, no per-stage artifacts, no resumability. **If the control doesn't exhibit the failure, stop — there's nothing to fix and no guidance to add.** This guards against writing guidance for a problem that isn't really in the skill.
4. Record verbatim *why* the agents interleave (do they cite efficiency? a single loop being "natural"? following an existing example in the skill?). That tells me whether the skill currently contains a bad example I should also fix.

**Micro-test the wording (cheap, before full scenarios):**
5. Two arms, same tempting tasks, 5+ reps each:
   - **Control:** current skill, no new guidance.
   - **Recipe:** current skill + my drafted recipe.
   - (Optional third arm — **prohibition:** current skill + a "don't interleave / never log mid-loop" version — to confirm on *this* case that the recipe beats the prohibition rather than assuming it.)
6. Score by reading every output manually: Does it produce named per-stage artifacts? Is each stage independently re-runnable? Does a failure report name the failed stage? Is logging at boundaries only? Watch for template echoes (an agent parroting "Extract/Validate/Transform" headers while still doing one interleaved loop underneath) — those are false passes and only manual reading catches them.
7. Treat **variance as a metric**: if the 5 recipe reps converge on the same staged shape, the wording is binding. If they diverge (5 different interpretations of "stage"), the form is too loose — tighten before adding words.

**GREEN / REFACTOR:**
8. Run the full pressure scenarios with the recipe in place. Success criterion: agent produces a staged script with inspectable per-stage artifacts, boundary logging, and resume-from-failed-stage behavior, *even under the efficiency/deadline pressure*.
9. If new rationalizations or new wrong-shapes appear (e.g. "I made stages but they all share mutable state so they're not really separable"), add a structural counter — a REQUIRED property in the recipe — not a prohibition. Re-test.

**Deploy only after** the recipe arm beats the control on every scenario and reps converge. Then commit and push.

One thing I'd flag back to you: if the baseline reveals the *current* skill contains an example script that itself does a single interleaved pass, the real fix is replacing that example — agents copy examples far more reliably than they follow prose. I'll know which after RED.