Before I write anything, let me classify this failure against the Iron Law and the failure-type table — because that classification determines the form of the guidance, and getting it wrong (e.g., reaching for a prohibition) measurably backfires.

## Classifying the failure

The complaint is: agents produce migration scripts that **interleave validation, transformation, and logging in a single pass**. They are not violating a rule they know under pressure — they're producing **output with the wrong shape**. Per *Match the Form to the Failure*:

> Complies, but output has the wrong shape → **Positive recipe or contract: state what the output IS.**
> Wrong form: prohibition list ("don't interleave stages").

So the guidance must be a **positive recipe / structural contract** describing the staged shape a migration script takes — not "never mix validation and transformation."

But notice: **I haven't earned the right to write this guidance yet.** The Iron Law applies to edits as much as new skills. I have a plausible diagnosis from a teammate report, not an observed baseline. I don't yet know:
- Whether the no-guidance baseline actually produces interleaving (or whether something in the *existing* skill is causing it).
- What the staged structure should concretely look like for *this* pipeline domain.

So my real first move is the verification plan, and the guidance text below is a **candidate** to be tested, refined, and possibly rewritten after I watch the baseline fail. I'm presenting both as requested, but the text is provisional on the RED phase.

---

## (1) Candidate guidance text

I'd add this as a section in `data-pipeline-authoring/SKILL.md`. It's a recipe/contract with a structural REQUIRED slot, deliberately *not* a prohibition list.

```markdown
## Migration Script Structure (Staged Passes)

A migration script IS a sequence of discrete, separately runnable stages over
the data — never a single combined pass. Each stage reads its input, writes a
durable output, and reports independently.

A migration script has these stages, in this order:

1. **Validate** — read source, check every record against expectations, and
   write a validation report (pass/fail counts + failing record IDs). Produces
   NO transformed data. Exits non-zero if any record fails.
2. **Transform** — read source + validation report, produce transformed output
   to a new location (do not mutate source). Operates only on records the
   validation stage passed.
3. **Load/Apply** — read transformed output, apply it to the target. Idempotent:
   re-running applies only what is not already applied.

Each stage is **independently invocable and re-runnable** (e.g. a CLI flag or
separate entrypoint per stage) and **logs to its own named log stream** so a
failure names the stage that broke.

When you emit a migration script, it MUST contain these three stages as
separate functions/entrypoints with the names `validate`, `transform`, and
`apply`. A reviewer must be able to point at one stage and say "this is where
it failed" and "re-run from here."
```

Key design choices, tied to the failure:
- **Recipe, not prohibition** — states what the script *is*, leaving nothing to negotiate.
- **No nuance/exemption clauses** — no "unless the migration is small." A real exception would become its own conditional on an observable predicate, only after testing shows it's needed.
- **Structural REQUIRED slot** — the three named entrypoints make the staged shape a thing the agent fills in, addressing the "logging interleaved / can't tell which stage broke" and "can't re-run part of it" symptoms directly.

---

## (2) Verification plan before deploying

**RED — establish baseline (do this first; the text above is provisional until it passes):**
1. Write 3+ realistic dispatch tasks: "write a migration script to do X" using the **current** skill as system-prompt context. Pick tasks that tempt a single-pass solution (tight data coupling, "just clean it up as you go" framing).
2. Run a **no-guidance control**: current skill, no new section. Confirm the failure actually reproduces — interleaved passes, undifferentiated logging, no per-stage re-run. *If the control doesn't fail, stop — there's nothing to fix here and the real cause is elsewhere.*
3. Record the *shape* of failures verbatim (where does logging land, are stages separable).

**Micro-test the wording (cheap, before full scenarios):**
4. Single fresh-context sample per variant, system prompt = full skill *with* the candidate section, user message = a tempting migration task. **5+ reps.**
5. Run three arms: no-guidance control, this **recipe** arm, and a **prohibition** arm ("never interleave validation/transformation/logging") — to confirm the recipe wins for *this* case rather than assuming it.
6. **Read every output manually** — automated grep for "validate/transform/apply" will count template echoes as successes. Verify the three stages are genuinely separable and re-runnable, not just named.
7. **Treat variance as a metric.** Five reps should converge on the same staged shape. If interpretations scatter, the contract isn't binding — tighten the structure (e.g., make the named entrypoints more prescriptive) before adding prose.

**GREEN / REFACTOR:**
8. Run full scenarios with the winning wording. If new wrong-shape patterns appear (e.g., agents make stages separate but still log to one stream), tighten the *structural* requirement, not by adding "don't" clauses.
9. Re-test until reps are convergent and stages are reliably separable.

**Deploy** only after GREEN: commit, push, consider PR.

I will not ship the section on the strength of the teammate report alone — that report is the bug filing, not the failing test.