# Effort Map — Claude Code reasoning settings for BFM-decomp > **Evolvable reference (docs/ layer). Created 2026-06-13.** Update freely as the harness changes — this is not the static constitution. > Companion to `CLAUDE.md` → "Reasoning & Model Protocol." CLAUDE.md points here; the per-phase guidance, the Max-vs-Ultracode rule, and the verified harness mechanics live here. **Where CLAUDE.md's tier language and this file differ, this file governs.** --- ## How the controls actually work (verified 2026-06-13) - **Effort ladder:** `low / medium / high / xHigh / Max`, set with `/effort` (slider) or `/effort `. This is *depth* — how hard a single agent reasons. `/effort auto` resets to model default. - **Persistence:** `low / medium / high / xHigh` persist across sessions (saved as the baseline). **`Max` and `Ultracode` are session-only** — they revert to the persistent baseline (currently xHigh) on a new session. **xHigh is the highest level you can make sticky.** To run Max, re-apply `/effort max` at the start of each session. - **Ultracode is NOT a deeper effort level.** `/effort ultracode` runs the model at **xHigh** *and* additionally turns on **multi-agent orchestration** (Claude fans out parallel subagents via Workflow). Same as putting the keyword `ultracode` in a prompt. Session-only. - **Why "Ultracode looks like xHigh":** because it *is* xHigh per agent — the indicator correctly shows xHigh. Ultracode adds **breadth** (parallel agents), not **depth**. - **Confirm what's active:** the status line next to the spinner (e.g. "with max effort"), `/status`, or `/effort` (slider position). --- ## The two axes (the key mental model) | | **Depth** — how hard one agent thinks | **Breadth** — how many angles at once | |---|---|---| | Control | `/effort` level (… xHigh < **Max**) | **Ultracode**, or Claude-driven **Workflow** fan-out | | Best for | one hard, irreversible reasoning problem | surveying / auditing / matching many independent items | | BFM examples | compiler fingerprint, US overlay-address derivation, phase planning, PhaseEnd synthesis | EXE-wide duplicate report, difficulty inventory, bulk matching of independent leaves | They are **not combinable via `/effort`** (it holds one value). And **global Ultracode caps every task at xHigh depth** — exactly wrong for the fingerprint/address work. So breadth is applied **surgically**: Claude proposes a Workflow fan-out for genuinely breadth-shaped tasks (you opt in) while single-thread depth stays at Max. --- ## Policy for this project 1. **Default working level = `Max`.** Usage is not a constraint (Max20 plan). Max's only cost is mild overthinking / latency on trivial tasks. Re-apply `/effort max` each session (it does not persist). 2. **Drop to `xHigh` only for speed** on purely mechanical Tier-3 stretches (installs, parser boilerplate, report scripts) when slow turns get annoying. Correctness is unaffected. 3. **Do NOT globally enable `Ultracode`.** It would run the deep, crown-jewel tasks at only xHigh depth. Instead, parallelism is surgical: Claude invokes Workflow/subagent fan-out for breadth-shaped tasks (you opt in). You *may* flip Ultracode on for an explicitly breadth-only stretch — accepting xHigh per-agent depth there. ### Proactively prompt for Ultracode on breadth-heavy stretches (proven, Phase 12) **Standing instruction (Drew, 2026-06-16):** during a **Max** session, the moment a **breadth-shaped, parallelizable** sub-task appears, **PROMPT Drew to enable `/effort ultracode`** — do not silently grind it serially at Max, and do not settle for a single one-off Workflow when a sustained fan-out would compound. Breadth-shaped = *the same analysis across many independent items*: bulk function matching / a whole-binary harvest, an EXE- or fleet-wide audit / survey / dedup, drafting C for dozens of functions, etc. (The litmus, encoded so I apply it: "would 10+ agents each doing one item beat me doing them in sequence?" — if yes, prompt.) **Why (the evidence):** Phase 12 ran the resident harvest under Ultracode and took it **1.4% → 71.7% byte-identical in one session** via 5 parallel-draft + byte-gate workflow passes (cookbook §12). Max-serial would have been an order of magnitude slower. Ultracode-on makes Workflow fan-out the *default* for every substantive task, which is what sustained the gains across passes — that compounding is the point, and it only happens if Ultracode is actually enabled, not improvised per task. **The prompt to use:** *"🟦 This stretch is breadth-shaped (~N independent items) — Ultracode (xHigh + multi-agent fan-out) would parallelize it; it took the resident 1.4%→72% in one Phase-12 session. Enable `/effort ultracode`? (I'll flip back to Max for the deep single-thread parts.)"* **Caveat — keep the deep work at Max.** Ultracode caps per-agent depth at xHigh, so it is *wrong* for the deep single-thread tasks (Phase-Start planning, the compiler fingerprint, US-address derivation, non-obvious debugging, PhaseEnd synthesis). The prompt is for the *breadth stretch only*; flip back to **Max** for those. And the judgment "is this actually breadth-shaped, or is it mine-to-author with full context?" is itself a Max call — writing a doc from this session's context is NOT breadth (subagents would have less context); fanning out a 134-overlay harvest IS. ### Effort is mapped per-task AND re-evaluated continuously — pause+prompt at EVERY transition (Drew, 2026-06-16) Effort management is a **per-task, continuously-re-evaluated** discipline, not a set-once choice. Claude cannot toggle effort itself, so it must **surface every transition** and wait for Drew to toggle: 1. **Plan-time mapping.** Every task in a phase plan is annotated with its recommended effort (R7) — the baseline map. 2. **Mid-task re-evaluation.** The right effort can be *revealed during* the work — a task planned at Max may surface a breadth-shaped parallel sub-task (bulk matching, a fleet survey). When it does: **pause → prompt `/effort ultracode` → wait for the toggle (a system-reminder confirms) → then run the Workflow.** Never launch multi-agent fan-out on a verbal "yes" before the toggle lands. 3. **Sub-task-done switch-back.** The moment the breadth stretch completes and work returns to deep single-thread (synthesis, design, the PhaseEnd): **pause → prompt to switch back to `/effort max`** (Ultracode caps depth at xHigh, wrong for synthesis). 4. **Task-completion hand-off.** At a task boundary, if Ultracode was used on the task just finished and the **next** task doesn't need it, **stop and prompt to switch before starting the next task** — do not roll into the next task at the wrong effort. Failure modes that motivated this (both 2026-06-16): (a) launched a harvest Workflow on Drew's verbal "Enable Ultracode" *before* he toggled it; (b) finished the 5 Ultracode harvest passes and continued straight into the deep T2–T6 work without prompting the switch back to Max — Drew had to ask. Memory: `effort-prompt-ultracode-on-breadth`. ### Evidence — Max vs Ultracode Workflow yield is the SAME for breadth harvests (controlled, Phase 13 T7, 2026-06-16) A controlled experiment (Drew's, prompted by "did the Max workflow do more than the Ultracode one?"): **80 fixed unmatched SC01/077 functions** (nins 8–15), the **identical** blind-draft Workflow + byte-gate, run once with **Ultracode** (xHigh agents, arm A) and once with **Max** agents (arm B) from the same committed baseline — the ONLY variable is the session effort the agents inherit. | arm | session effort → agent depth | byte-matched (of 80) | |---|---|---| | A | Ultracode → **xHigh** | **13** | | B | Max → **Max** | **14** | Overlap: **A∩B = 12**, xHigh-only = 1, Max-only = 2 (union 15). **13 vs 14 is noise** (a 1-function delta, ~80% of the union shared) — per-agent effort depth does **not** meaningfully change blind-draft harvest yield. The pre-experiment observation that "pass 1 at Max matched 92% vs later Ultracode passes' 54%" was **confounded by function difficulty** (pass 1 = the easiest functions), not effort. **Decision this settles:** for **breadth harvests, prefer Ultracode** — it delivers the same per-agent yield as Max AND the multi-agent orchestration, so there is no yield cost to using it. Keep **Max** for deep single-thread synthesis (planning, fingerprinting, PhaseEnd) where reasoning depth is the bottleneck, not parallel coverage. *(Caveat: one trial per arm — directional, not definitive; rules out a LARGE effect, not a small one. Re-test with multiple trials if a future task hinges on a subtle difference.)* --- ## The decision rule — Max vs xHigh vs Ultracode - **Max** — a wrong answer poisons everything downstream and is hard to reverse, **or** root cause is unclear (non-obvious debugging), **or** it is deep synthesis (phase plan / PhaseEnd). *Depth matters.* - **xHigh** — the design is already settled in the approved plan and this is execution; single-file, clear-requirements, mechanical. (Also the highest *persistent* baseline.) - **Ultracode / Workflow fan-out** — the task is "run the same analysis across many independent items" (survey, audit, dedup, bulk match). *Breadth matters more than per-item depth.* Live heuristic, in order: 1. Is the design already settled in the approved plan, and this is just execution? → **xHigh.** 2. Is this a phase plan, a PhaseEnd, a genuine architectural fork, or non-obvious debugging? → **Max.** 3. Would a wrong answer systematically poison everything downstream *and* be hard to reverse? → **Max** (the "use sparingly" tier). 4. Is it the same analysis across many items? → **Ultracode / Workflow.** --- ## Per-phase map (Gen1) **Constant for every phase:** the **Phase Start plan** and the **PhaseEnd file** → **Ultracode minimum; Max only for the heavy phases (3, 6) and the Gen1-exit PhaseEnd (7)**. Mechanical-phase PhaseEnds (2, 4, 5) are fine at xHigh/Ultracode — the synthesis is bookkeeping, not novel reasoning. (Confirmed 2026-06-13: Drew called Max unnecessary for the Phase-2 PhaseEnd.) | Phase | **Max — mandatory (never drop)** | **xHigh — fine (drop for speed)** | **Breadth — Ultracode/Workflow helps** | |---|---|---|---| | 1 — RE stack + import ✅ | — | (ran at ~xHigh; correct — headless scripts) | — | | 2 — Extraction pipeline | none on first pass; escalate **only if** LZSS cross-validation vs CUE fails (non-obvious debugging) | ISO9660 walker, .CD/PAC splitter, LZSS decoder (first pass), SQV awareness, sha1 manifest, format docs | — | | 3 — File-loader & overlay map | ⭐ **US address derivation** (resident blob + ≥1 overlay) **+ PCSX-Redux RAM-dump proof**; the deep RE call-chain tracing | ledger seeding, blob import *once proven*, map write-up | (optional) surveying many candidate loader functions | | 4 — Build toolchain | none | **everything** — apt installs, sha-verified compiler fetch, `make check-env`, version recording | — | | 5 — splat config + byte-match | splat `.yaml` section-boundary authoring/debugging (esp. if the clean link fights back) | Makefile pipeline, `check.us.sha`, `make expected` | — | | 6 — Compiler fingerprint + first matches | ⭐⭐ **compiler-fingerprint ladder + arbitration** (the single highest-stakes task in Gen1); first matches incl. LZSS (proving loop + pin) | recording the pinned triple, `decompile.py`/asm-differ wiring, INCLUDE_ASM headers | (later) bulk matching of independent leaf functions | | 7 — Loop at scale + Gen1 close | Gen1-exit synthesis (in the PhaseEnd); first jump-table match; loader-cluster matching (deep) | report scripts (difficulty/dup/progress), README | ⭐ **EXE-wide duplicate report + difficulty inventory + bulk matching** — real Workflow fan-out wins | **The Max shortlist** (reach for the ceiling only here): (1) Phase 6 fingerprint ladder, (2) Phase 3 address derivation + RAM proof. Conditional escalations: Phase 5 splat config if the link won't go clean; the Phase 7 Gen1-exit PhaseEnd. --- ## Plan-mode (Phase Start) effort Phase Start planning is deep single-thread synthesis → **Max**. Mandatory-Max for Phases **3** and **6**; xHigh would suffice for the mechanical phases (2, 4, 5, 7) but since Max is the default, just leave it. Use **Ultracode during planning** only when the plan needs broad reconnaissance first (surveying many candidate functions) — realistically only Phase 3 and Phase 7. --- ## The Effort-map check (Rule R7 — formalizes at PhaseEnd_Phase2) - **Before each Phase Start plan:** state the recommended effort for *planning that phase* (per this file) and confirm the developer has it set. - **In the phase plan:** annotate every task with its recommended effort level. - **At every task handoff** and in the Session Start "next task" statement: restate the recommended effort. - This file is evolvable — correct it as the harness changes or as the per-phase reality is learned.