Understand Until Simple

---
name: understand-until-simple
description: Use this skill BEFORE writing code for any task you're tempted to call "hard / tough / complex", any "why is X slow / where's the bottleneck", any "should I optimize Y", any concurrency/perf/kernel/scheduler investigation, or any time you catch yourself hand-waving a root cause. It is the pre-implementation understanding GATE — decompose to the atomic (line/kernel/buffer) level, get MEASURED evidence, let measurement correct your hypotheses, until the problem is SIMPLE and quantified. Only then write code. If it still feels hard, you haven't decomposed enough.
version: 1.1.0
---

# understand-until-simple

The pre-code gate. Operationalizes §0 (SOLID) + §0.1 (decompose to the implementation level) into a
checklist you clear BEFORE writing implementation code.

Born from the DSv4 concurrency case (2026-06-14): I kept calling batched decode
"very hard", proposing it as a multi-day lever on hypothesis. ckl's
correction — *"the way you're talking means you don't understand it at all —
'so hard, so tough'; we start work only once you've figured it out and consider
it simple"* — was right. Reading the code + measuring collapsed it to:
**it's one `for r in 0..n` loop (`dsv4.rs:1872`); batch it → ~2×; pieces exist;
MoE won't cap it.** Simple. The "hard" was just un-decomposed.

---

## The law

**"Hard" is a confession that you haven't decomposed it yet.** Difficulty is not
a property of the problem; it is the distance between you and the atomic
mechanism. Close that distance until the problem is simple, then the code writes
itself. A plan that still sounds hard is a plan you don't understand.

**No code until you can state the fix in one simple sentence with a measured
number behind it.** ("Batch the per-row attention loop → ~2× aggregate, MoE
stays sub-linear" — that sentence is the license to start.)

---

## The gate (clear every step before coding)

### 1. Catch the hand-wave
If your description contains "hard / tough / complex / tricky / multi-day / it's the
lever" WITHOUT a line number and a measured number, STOP. You are at hypothesis,
not understanding. The words "hard / tough" are the alarm.

### 2. Decompose to the atomic level — READ THE ACTUAL CODE
Not "attention is slow" → **"`dsv4.rs:1872` is a `for r in 0..n` loop calling
single-row `mla_attention` + 2 memcpy per row."** Not "prefill is serial" →
read `planner.rs` and find it's chunked + mixed-batched (so the real cause is
elsewhere). Name the exact file:line / kernel / buffer / loop. If you can't, keep
reading. **Read the module's existing unit tests too** — they are the
highest-density local evidence and often already encode the invariant you're
questioning (a passing reconstruction test can settle "is this a bug?" in
seconds). Source survey / call-graph / "it must be X" are HYPOTHESIS, never
evidence (§0).

### 3. List your hypotheses — then refuse to guess the load-bearing one
You will have a guess for what dominates ("MoE ∝ active_experts is the real
wall"). That guess is exactly the thing you must MEASURE, not assert. The
load-bearing assumption is never the one you skip.

### 4. Measure — controlled, single-variable, the right framing
Profile / A-B the controlled variable (c=1 vs c=8; before vs after; with vs
without). step-profiler, nsys NVTX, `/v1/stats` deltas, wall-clock Δ%. Decompose
the cost into named buckets and get each bucket's scaling. Wall-clock /
per-request framing is ground truth; a narrow-window % is not (§0 framing trap).
For the perf A/B mechanics (formula → binding constraint → matched A/B →
license-or-kill) use the **kernel-optimization** skill — this skill is the gate
that precedes it.

**Evidence tiers — local vs pod (ARLE-specific).** Not all evidence is
equal-cost. **Tier-1 (local, cheap):** reading the exact loop, the module's unit
tests, `cargo test`, deterministic control-flow tracing — *enough to settle a
correctness/logic question and to kill a structural hypothesis.* **Tier-2
(pod/GPU, expensive):** nsys, runtime counters, wall-clock Δ% — *required before
any perf default-flip.* Clear the gate on Tier-1 for correctness work; for a perf
claim, Tier-1 may sharpen the file:line and kill a hypothesis, but the
license-to-flip number is Tier-2 — label it **"gate cleared on correctness;
perf-license pod-gated"** rather than treating the problem as unfinished. Don't
let "most ARLE evidence is pod-gated" block local correctness work.

### 5. Let the measurement CORRECT you
The point of measuring is to be wrong cheaply. (DSv4: MoE was NOT the wall —
3.70× sub-linear, not ∝c; and `--spec-type mtp` silently *disabled* the batched
lane — `executor.rs:1563`.) A wrong root cause wastes every downstream hour (§0:
root-cause hypotheses also get license-or-kill). Update the picture; re-decompose
if needed. **The measurement can also kill the *premise*:** "X is broken" becomes
"X is correct-by-design, proven by `test_foo`". That is a *successful* gate
clearance — you now understand it — not a dead end. Record the proving test and
stop; there's no fix to write.

### 6. Reach simple + quantified
Write the one-sentence fix with its number and its file:line. Name the next wall
(there's always one) and why it's softer. Name the one wrinkle (DSv4: MTP↔batched
exclusivity). If you cannot compress it to a sentence + a number, you are not
done — go back to step 2.

### 7. NOW write the line-level spec, then code
The understanding produces an implementation-level spec the executor copies
verbatim (§0.1: every mutated buffer + call site + precondition). Code only after
the gate is clear.

---

## Done test — two gates

Split "I understand it" from "I'm licensed to ship perf". They have different bars.

**Understanding gate — clear this to write the line-level spec / a correctness fix:**
- [ ] The bottleneck/mechanism as a **file:line / kernel / loop**, not a concept.
- [ ] At least one **hypothesis the evidence killed** (if zero, you didn't test the load-bearing one — or the premise was right, which is rare; double-check).
- [ ] The conclusion in **one sentence** (a fix, OR "correct-by-design, proven by `test_foo`").
- [ ] It feels **simple**. Still feels hard → back to step 2.

**License gate — clear this ADDITIONALLY to flip a default / ship a perf win:**
- [ ] A **measured** decomposition (numbers, not "should be"), controlled-variable — Tier-2 (pod) for perf.
- [ ] The fix's **expected number** (the Δ% / the new floor).
- [ ] The **next wall** named, and why it's acceptable for now.

Understanding gate incomplete → still in understanding, do not code. A correctness
fix may ship on the Understanding gate alone when a unit test pins it. A perf
default-flip needs BOTH gates — and the License gate's number is usually
pod-gated; mark it explicitly when deferred.

---

## Anti-patterns (this is how the gate gets skipped)

1. **"It's hard, so it'll take a while" as a substitute for decomposing.**
   Hardness estimate ≠ understanding. The DSv4 lever went from "3-4 week new
   infra" → "wire one for-loop" purely by reading the code.
2. **Proposing the lever on a hypothesis ("X is the bottleneck, batched-Y fixes
   it") without the measured decomposition.** `plan_label`/"X must dominate" is
   reachability, not a license (cross-ref kernel-optimization anti-patterns).
3. **Skipping the measurement of the load-bearing assumption** because the code
   "looks like" it confirms the guess. Code-reading and measurement share
   blindspots only sometimes — measure the thing that decides the plan.
4. **Extrapolating from a smoke shape** (short context, c=1) to the production
   regime (long context, c=8). Re-measure at the binding shape (§ distilled
   lessons: SLO verdict from the SLO workload).
5. **Calling it understood when you can't say it simply.** Complexity in the
   explanation = gaps in the understanding.

---

## When NOT to gate

Trivial / mechanical edits (rename, config flip, a ≤3-file obvious change), or a
task already decomposed + measured this session. The gate is for the things you'd
otherwise hand-wave as "hard" — that's exactly where it pays.

If a **shared working tree is mid-edit** (a concurrent agent's WIP), prefer
targeted reads + per-function reasoning over a full `cargo build`/workspace test —
the other agent's half-state can break the build for reasons unrelated to your
question. Tier-1 evidence still works; just scope it to the files you're reading.