E2e Driven Iteration

E2E-Driven-Iteration — inner loop (∂L/∂code), the forward-pass cadence

The Metaphor

The lab scientist with a hypothesis. Before any intervention: measure the baseline. After any intervention: measure again. Between the two measurements: exactly one change. "I know what this reagent does" without running the control experiment is not science — it is storytelling. The E2E run is the measurement device. Skipping it turns every edit into a story and leaves the loss unexamined.

Overview

In Gradient Descent for Agents, the E2E run is the forward pass. Every iteration of the inner loop has one: it produces the loss number this iteration descends against. This skill enforces the rhythm measure → diagnose → fix → measure inside loop-driven-engineering. The existing dach-skill says "run E2E when warranted." That's too soft. Under time pressure, "warranted" silently becomes "never" and the iteration degrades into blind-patching based on stale assumptions.

Core principle: when you are in a fix-loop (trying to close a failing signal), every iteration begins and ends with an E2E run of the failing case. The E2E is the forward pass; its output is the loss; the delta between iterations is the gradient signal that tells you whether the last edit helped or regressed.

No E2E at the start → no loss measurement → your edit is speculative. No E2E at the end → you don't know if you converged or just stopped.

See ../../docs/ldd/convergence.md §5 for how this skill implements the loss trace across the test pyramid.

When to Use

Invoke at the start of every inner-loop iteration whose purpose is:

• Fixing a failing test
• Closing a rejected gate
• Resolving a production incident
• Debugging an unexpected behavior
• Converging on any goal where "is it fixed yet?" is the question

Do not use for: new-feature work where there's no failing E2E yet (write the E2E first, then enter this loop), pure refactors (no behavioral E2E to run), documentation-only changes.

The Six-Step Iteration

k-th iteration:
  1. Run E2E        → loss_k = measured rubric score / failing items
  2. Compare        → Δloss_k = loss_{k-1} − loss_k  (was the last edit a step or a random walk?)
  3. Diagnose       → invoke root-cause-by-layer, name layer 4/5
  4. Fix            → one focused edit, smallest coherent unit, at the named layer
  5. Run E2E again  → loss_{k+1} becomes loss_k of iteration k+1
  6. Emit trace     → python -m ldd_trace append ...  (see using-ldd §"Persisted trace")

Do not skip step 1 — "I know what broke, I'll just fix it" is the anti-pattern. Until you measured the current state, you don't know if the last change helped, hurt, or was a no-op.

Do not skip step 2 — if Δloss_k ≤ 0, the previous edit did not help. You are in oscillation or a local minimum. Invoke loss-backprop-lens before proposing another edit.

Do not skip step 5 — without the post-edit run, "fixed" is a claim, not a measurement.

Do not skip step 6 — the user needs to see the loss descend live, per-iteration. v0.5.1 makes this a hard step, not an optional summary at task end. Running python -m ldd_trace append ... appends to .ldd/trace.log AND prints the full trace block (sparkline + chart + per-iteration line) — one command satisfies both mandates. If the tool is unavailable, render the trace block manually per using-ldd/SKILL.md §"Loss visualization".

Red Flags — STOP, the loop is degrading

• "I'll fix it then run the E2E at the end" → no loss measurement per step; you won't notice regressions
• "The E2E is slow, I'll skip it this iteration" → you lost the gradient
• "The last edit probably worked, don't need to re-run" → you don't know
• "E2E keeps failing the same way, let me try something else" → Δloss is not going down; step size wrong (invoke loss-backprop-lens)
• "I'll run the unit test instead, same signal" → only if the unit test covers the same failure surface; otherwise you're measuring a different loss
• "Let me batch 3 fixes and run once" → conflates 3 gradient steps; if one regressed, you can't attribute
• "I'll emit the trace block at the end of the whole task, the user doesn't need it per iteration" → NO. The user CANNOT see convergence without per-iteration emission; a final-block-only cadence gives them a single data point instead of a trajectory. Per-iteration trace is step 6, not optional.

E2E selection — cheap before expensive

If the failure reproduces at a cheaper pyramid tier (unit, integration), iterate there first. Only escalate to full E2E when the cheap tier can't reproduce.

Running full E2E for a typo catchable at unit tier is a pyramid violation; it wastes budget and slows the gradient signal. Running only unit tests for a cross-boundary contract bug misses the real loss surface.

Budget interaction

This skill runs inside loop-driven-engineering's K_MAX = 5. The E2E-per-iteration cost sets a floor on how fast iterations can happen; if one E2E takes 30 minutes, your total budget is 2.5 hours. Plan accordingly:

• Before entering the loop, estimate E2E cost and multiply by 5 — that's your budget ceiling
• If estimate > available time, either cheapen the E2E (subset of scenarios, fake externals) OR accept you'll hit K_MAX and escalate
• At K_MAX: escalation per loop-driven-engineering's §Escalation — with the added requirement of attaching the loss_k trace across all iterations

How to Apply — checklist

1. Define the failing E2E. Exact command, expected state, measured state. Save the output of iteration 0 as loss_0. If .ldd/trace.log exists in the project, first run python -m ldd_trace status --project . to see prior iterations.
2. Enter the loop. At the start of each iteration: run E2E, capture loss_k, compare to loss_{k-1}.
3. Interpret the delta. Negative → progress, continue. Zero → no-op, rethink. Positive → regression, revert immediately and re-diagnose.
4. Diagnose via root-cause-by-layer. Calibrate via loss-backprop-lens.
5. Edit smallest coherent unit.
6. Rerun E2E. That's loss_{k+1}.
7. Emit trace block. Run python -m ldd_trace append --project . --loop inner --auto-k --skill <skill> --action "<what changed>" --loss-norm <v> --raw <n>/<max>. The tool appends to .ldd/trace.log AND prints the full trace block — show the output to the user.
8. Close only when E2E is fully green AND the regularizers (contracts, docs) are honored — hand off to docs-as-definition-of-done. Run python -m ldd_trace close ... to record terminal status.

Common Rationalizations

Relation to other skills

• reproducibility-first runs before this skill enters the loop — you must have a reproducible signal to begin.
• root-cause-by-layer runs at step 3 of each iteration — diagnosis.
• loss-backprop-lens runs when Δloss ≤ 0 to recalibrate step size.
• loop-driven-engineering is the parent — this skill is what it dispatches during a fix-loop.
• docs-as-definition-of-done runs at close — when the E2E is green, the loop isn't closed until docs are synced.

Real-World Cue

If your iteration log for a bug fix doesn't show a loss_k trace — one number per iteration, visibly decreasing toward zero — you were not doing E2E-driven iteration. You were hoping.