Occam

Occam

Agents should not be multiplied beyond necessity.

Occam answers a question one level above "how do I execute?": what shape should the computation be? Over-orchestration burns ~15× the tokens and rots into state drift; under-orchestration crams five specialties into one context until the agent loses the plot. The target is minimal sufficient topology.

Step 0 — Interview only if ambiguity blocks execution

Infer goal, success criterion, boundaries, and constraints from the request and the workspace. Ask only what actually blocks execution — at most 2–3 questions, in one message. The one thing you may not proceed without is a verifiable success criterion (test suite, checklist, spec to diff against); if it can't be inferred, that's the question worth asking.

Step 1 — Select the topology

if one artifact and one goal, and the working set fits one context:
    → Tier 1 (loop)

elif the work is N independent items (no item needs another's output,
      no two items write the same file, each verifiable alone):
    → Tier 2 (fan-out)

elif any Tier 3 trigger below fires:
    → Tier 3 (graph)

else:
    → Tier 1

Tier 3 triggers — each measurable before running; any one suffices:

1. Working set (inputs that must be actually read + artifacts kept live) exceeds ~60% of one context window.
2. ≥3 heterogeneous output artifacts that must stay mutually consistent (architecture + plan + docs; spec + code + tests-as-contract).
3. ≥2 distinct competencies with hand-offs, where neither competency can verify the other's output (legal vs code; research vs implementation).
4. An irreversible or externally visible stage that needs an isolated node with independent verification (deploy, data migration, publication).

Confidence rule: not sure a higher tier is needed → go down one. Uncertainty is evidence for the simpler shape.

Escalation rule: a tier is not a life sentence. When mid-run facts prove the shape wrong — context drowning, items turning out independent, a stage needing a real specialty — stop, say so, promote one tier. Demotion needs no ceremony; promotion requires the evidence you just collected. This is why defaulting down is safe.

Announce the decision in two lines before executing:

Topology: Tier 2 — 40 files, independently fixable, nothing shared.
Estimated cost: ~1 pilot + 40 cheap contexts + 1 synthesis

Cost table, worked examples, and extra Tier 3 markers (output volume, competency distance, blast radius): references/calibration.md.

Step 2 — Execute

• Tier 1 & 2 → references/loop-patterns.md.
• Tier 3 → answer the gate, then references/graph-patterns.md.

The gate (three questions, before any Tier 3 run):

1. Can the graph collapse into one loop or one flat fan-out with nothing real lost? Then collapse it.
2. Do the states partition? Every file/key gets exactly one writer. If ownership can't be partitioned, the work is coupled — one loop.
3. Is verification independent? Someone other than the producer checks each merge point, never on a weaker model than the producer's.

Napkin sketch, spend caps, failure isolation — consequences of these three; all in graph-patterns.md.

Verification policy

Adversarial self-review is the default: switch stance, try to break the result, run the real checks, paste the evidence. A separate verifier agent is required only when stakes justify its cost: external effects or irreversible changes, published/final output, safety, large fan-out, or any Tier 3 merge point. Evidence before claims in every mode; an unverifiable claim is reported as unverified, never rounded up.

Model tiering

By node role: cheap — mechanical (extraction, mass uniform edits); standard — workhorse (implementation, research, drafting); top — judgment (synthesis, judging, final review, architecture). A reviewer is never a weaker model than what it reviews. Cheap nodes buy wide fan-out; top nodes count individually against the spend cap.

Runtime

Use the best the harness provides: a workflow/orchestration tool if present; otherwise plain subagents (Tier 2 = one message with N parallel calls; Tier 3 = you walking the milestone DAG — both variants of every pattern are in graph-patterns.md); with no subagents, run Tier 1 discipline inline and say what would have benefited from parallelism.

Universal rules

• Plan is a file, not a vibe — persist it; re-read it, don't recall it.
• Decompose by context boundaries, not by roles.
• References, not payloads — subagents return a path + ~100-token summary.
• Structured mandates — objective, output format, tools, boundaries.
• Checkpoint, don't restart — retry only the failed branch, telling it what failed.