Fla Optimization Loop

3. Iteration protocol

Every iteration is exactly three steps, in order, with no telescoping into the next iteration between them:

1. Make one change to the kernel.
2. Run verify.py — gate must stay green; record the bench number.
3. Append one row to OPT_LOG.md (see references/opt-log-template.md) and git commit.

A failed or no-change iteration is still an iteration: log it and commit before debugging the next direction. (Borrowed from AKO4ALL: bench → log → commit, the most-skipped step in practice.)

Stall handling. After 3 consecutive iterations with no improvement (≥ a few % over current best, above noise), stop and re-assess: re-profile, re-read OPT_LOG.md for which axes you've already tried, and search for known techniques for this op family before picking a new direction.

When to stop. A user-set iteration cap is reached; or re-assessment produces hard evidence of a floor (bandwidth-bound at HBM limit, launch-overhead dominated, timer-resolution limited — cite it in OPT_LOG.md); or you've documented ≥3 distinct directions tried with evidence. Don't stop silently because a tool (e.g. NCU) was unavailable — that's a re-assessment input.

No-go bar. If stopping means concluding there's no win to promote — a no-go — that verdict has its own bar: a first candidate losing doesn't clear it. A no-go needs a recorded baseline number, at least one reasoned candidate attempt (not a blind guess), the gate status, the bench evidence, and a named active bound or blocker (name which roofline/launch/timer limit, with the number). Without those five it's an unfinished loop.

4. Reproducibility

• Seed — the tests already pin torch.manual_seed(42); don't undermine it.
• Environment — verify.py prints GPU / CUDA / PyTorch / Triton / commit SHA; paste that line into OPT_LOG.md so a number is interpretable later.
• Full-shape verdict before promotion — a --gate-k subset is a signal only.
• Rank by the solution's own runtime for fast iteration signal; pay for the full --base main comparison only at the verdict. Clock noise on unlocked GPUs can swing absolute speedup — see references/TRAPS.md.

5. Silent-bug & measurement traps

Read references/TRAPS.md before trusting any number. It catalogs FLA-specific traps (NaN poisoning on partial writes, TF32 inflating fp32 reference diffs, assert_close relative tolerance, one-sided numeric-flag relaxation, autotune-cache staleness across edits, int64 address arithmetic, implausible speedups that signal a silently-skipped path). When you hit a new one, add it there with Fact / Why / How to apply so the next session doesn't re-learn it. (Borrowed from AKO4X's TRAPS.md.)

6. Evidence records (scratch workspace)

Keep your search artifacts in a git-ignored directory — profile/<op>-opt/ is already ignored:

profile/<op>-opt/
  docs/draft.md       # the task contract (§1)
  OPT_LOG.md          # one row per iteration (template in references/)
  dispatch.md         # one row per shape bucket — only if Phase 3 specializes (template in references/)
  TRAPS.md            # traps you hit this session (seed: references/TRAPS.md)
  trace/              # torch.profiler / NCU artifacts (kept out of git)

Each kept candidate's kernel gets a short header (Identity / Delta / Lessons / Dead-ends / Open-directions) per references/opt-log-template.md, so a later session can see what was tried and why.

7. Promotion → MR

A candidate is promotable only on a full green gate plus a measured, repeatable win on the target shapes, and a profiler/roofline reading that explains the win (or, for a no-go, the blocker) — a speedup you can't account for is a silent-skip suspect, not a result (see §5). Then:

• Keep the diff minimal — change only what the win needs, plus light cleanups (CONTRIBUTING "Protect battle-tested paths; keep diffs minimal").
• Collect perf evidence per backend skill — fla-nvidia-performance (before/after, NCU summary, dense + varlen coverage) or fla-ascend-performance (before/after, pipe/UB metrics, round summary template) — and a full final-claim stats block (median/mean/std/min/p10/p90 per shape, equal-weight geomean speedup, exact commands, baseline commit + candidate SHA, GPU id/model with idle-clock evidence — the last guards the clock-drift trap in §5).
• Package the PR per fla-mr-readiness.

The scratch workspace under profile/<op>-opt/ stays local; it is not part of the PR.