# Occam

> Execution-topology selector for non-trivial tasks: decides the simplest sufficient execution shape — a single disciplined loop, a loop with parallel fan-out, or a milestone graph with shared state — states its cost, and executes it. Use whenever the user invokes /occam, or brings a task that is clearly multi-part or large-scale: "audit this thoroughly", "migrate all X", "research this across many sources", "build this feature end to end", "refactor the whole module", "process every file in this folder". Also use when the user asks how to split work between parallel agents or whether a task needs multiple agents. Most tasks are a loop; never reach for a graph unless the work forces it.

- Skill: `artemavrin/occam` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add artemavrin/occam`
- Raw SKILL.md: https://api.skillmd.com/api/skills/artemavrin/occam/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: artemavrin (https://skillmd.com/u/artemavrin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/artemavrin/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.