—

One agent, one task, from the moment you ask to what survives afterwards.

The transcript is not the interface. In a tool-using agent, conversation is the control and negotiation layer. Plans, diffs, approvals, tool calls and artifacts are first-class structured objects that the conversation refers to, commands, and takes responsibility for.

Claude Code, Cursor’s agent mode, Aider, Devin and a dozen internal tools have each independently grown an approval prompt, a streaming renderer, a tool-activity log, and a way of saying “are you sure?” — and none of them call these things the same name. The literature that exists is either conversation design, mature but grown from voice assistants, or agent UX, current but a flat list of tips.

What is missing is the middle: a vocabulary with enough rigour to design against, argue with, and refuse. These fourteen are a proposal for it. Each states what it costs and when it does not apply, so it can be argued out of the catalogue rather than merely admired.

The line this stands in

The template is inherited, deliberately. It is the Gang of Four’s, from Design Patterns (1994), and theirs was adapted from Christopher Alexander, who was describing towns, buildings and where the light falls. Fourteen entries in this shape are an act of inheritance, not a coincidence of formatting.

In 1996 Alexander told a room of object-oriented programmers that they had taken his format and left the rest behind. A pattern language is meant to be generative — a sequence you can follow to produce a coherent whole, not a shelf of separable good ideas — and patterns are finally judged by whether what they generate is good for the people who have to live inside it.

Both halves bear on this page. The first is why Related Patterns is navigation here rather than a list at the foot of a page: a language is meant to be moved through, in the direction its relations point. The second is why every entry carries a Failure Signature — in an exchange the defect leaves no mark on the artifact, only on the person, so naming what they experience is the only way they get a vote. The fuller version of this, in the first person and signed, is the preface to OM-005.

The shape of it

The patterns are not a list. They sit at defined points on the loop a delegated task travels — most arguments about agent design are really arguments about which arc you are on. Choose a stage to filter the index.

The fourteen

1. 01Capability DisclosureMake the agent’s powers, position and limits legible before the person commits.
2. 02Mode VisibilityMake the active mode visible at the moment of use, not merely settable.
3. 03Streaming TurnEmit as you produce, so the wait overlaps the work instead of following it.
4. 04Barge-InLet the person seize the turn, and say what that stops.
5. 05Assume or AskAsk only when ambiguity changes the blast radius; otherwise state an assumption.
6. 06Constrained ChoiceWhen ambiguity is enumerable, offer structure rather than free text.
7. 07Plan, Approve, Execute, ReceiptFour phases, so consent happens where judgement is still useful.
8. 08Tool-Call TransparencyWhich tool, against what, why, and with what result: as structure, not prose.
9. 09Ambient Activity ChannelSignal state through a channel perceived without being attended to.
10. 10Approval GateExplicit, per-action consent before anything irreversible or outward-facing.
11. 11Progressive AutonomyScope widens with demonstrated reliability and narrows with risk.
12. 12Honest GaugeA signal must be wrong only when the system is wrong.
13. 13Recoverable ExecutionEvery action has a visible before-state and a path back.
14. 14Durable MemoryWhat matters survives in durable, correctable memory, not transcript length.

Reading this page

• The index on the left holds all fourteen, grouped by stage. [ and ] step through them.
• Patterns, at the top of the rail, changes which section you are in. There are four — one agent, many agents, arrangements of many, and one person running several teams — and they describe different things. A relation may point across them, and following it switches the rail with you.
• Related patterns on every entry are clickable. That field has been a dead list at the foot of a page since 1994; here it is how you move.
• Side of the seam splits them by how they fail. Harness patterns live in code — they fail the same way every time and a test can hold them. Disposition patterns live in the agent’s character — they fail stochastically, and you strengthen a tendency rather than pin a behaviour. Nine are harness, one is disposition, four are both: most of what makes an agent feel trustworthy turns out to be buildable.

Which paper is canonical

In OM-001 · Conversational Agent Control Surfaces, which is canonical for them. Every entry here is reproduced from it in full and links back to it. The paper is where they are written, and where a correction lands.

Four of the fourteen — Mode Visibility, Streaming Turn, Ambient Activity Channel and Honest Gauge — were found by hitting them on a single workstation running a voice-first agent with a resident process, local speech-to-text and synthesis, and a physical lighting channel. Every number quoted in those entries was measured on that machine rather than estimated.

One dispatcher, many units. What changes when a delegated task is split.

The fourteen One Agent patterns describe one delegated task, and the vocabulary says so: a turn is the unit of exchange, and the thing held by exactly one party. Put twelve agents in flight and the turn disappears, leaving nothing to hold, nothing to interrupt, and no moment at which the person and the agent are both present.

So this is a second language rather than an extension of the first. Its topology is a fan-out and a fan-in, and everything difficult lives at the two seams and in the space between them, where the person is absent by design.

The eight

1. 01Proposed DispatchThe context that holds the work proposes the units; the person approves rather than authors.
2. 02Authority at DispatchAuthority granted at dispatch, because per-action approval does not survive N.
3. 03Isolation by ConstructionA workspace per unit, so collision is impossible rather than unlikely.
4. 04Fire and ForgetA dispatch that needs watching cannot be followed by another.
5. 05Status BoardEvery unit's state on one surface, at the granularity the channel carries.
6. 06The Return PathA result routes back to what commissioned it, without a human as transport.
7. 07Nested AttributionA receipt names who acted, and how far down.
8. 08GatherN reports reconciled into one account, with disagreement surfaced.

Which paper is canonical

In OM-002 · Working with Many Agents, which is canonical for them. Every entry here is reproduced from it in full and links back to it. The paper is where they are written, and where a correction lands.

Named ways to arrange many agents. Not patterns, but compositions of them.

The eight Many Agents patterns can be assembled into different wholes, and an arrangement earns a name only when it passes one test: a composite is worth naming when it changes what its constituent patterns mean.

These are the closest this catalogue comes to what Alexander meant by a pattern language rather than a pattern list: a sequence you can follow to produce a coherent whole, rather than a shelf of separable good ideas. Whether they reach it is argued, and doubted, in the paper.

The six

1. 01Plain Fan-OutThe default, named so the others read as departures rather than inventions.
2. 02PipelineUnits in series, each report standing as the next one's commission.
3. 03Scout then SwarmOne read-only unit produces the decomposition; then fan out over it.
4. 04Loop Until DryRounds until consecutive ones return nothing new: for work of unknown size.
5. 05PanelSeveral units, same question, kept apart, and the disagreement is the product.
6. 06Adversarial VerifyUnits commissioned to refute, with the rule fixed before the verdicts arrive.

Which paper is canonical

In OM-003 · Arrangements, and Many Teams, §7–§12, which is canonical for them. Every entry here is reproduced from it in full and links back to it. The paper is where they are written, and where a correction lands.

One person, several teams. The level where the dispatcher is human.

The recursion stops here, and that is the whole finding. Among the Many Agents patterns the dispatcher is an agent: you can scope its authority, give it a return address, and hold it to a report. At the level above, the dispatcher is a person, who has none of those properties — a human cannot be commissioned.

Everything difficult at this level falls out of that asymmetry. Authority that cannot be scoped, no address that resolves, no report, and a scarce resource that is attention rather than compute — attention does not divide, and cannot be bought.

The three

1. 01Ordered by ReadinessOrder the surface by what needs a person, not by what is happening.
2. 02Re-entry NoteComing back to a team should cost reading rather than reconstruction.
3. 03Landing OrderThe shared trunk is the one thing isolation cannot copy.

Which paper is canonical

In OM-003, §14–§17, which is canonical for them. Every entry here is reproduced from it in full and links back to it. The paper is where they are written, and where a correction lands. That document also leaves one question open on its face: whether an agent can run this level at all.

The channel you do not look at. What a machine reports when there is no turn in progress, and may never be one.

The first four sections are focal and single-channel — they assume a surface you are looking at. Nobody wrote that down, because there was no alternative to contrast it with. Ambient Activity Channel introduced the alternative in one entry; this is what it looks like as a set.

A peripheral surface has one hue, one rhythm and one brightness; it costs nothing to consult because it is already in the eye; it never scrolls away; it has no history at all; and its audience is the room rather than you. Every rule here falls out of those five facts. No history is why re-assertion beats change detection. One slot is why precedence is the entire safety model. The room is why two more lamps would break darkness-as-alarm.

The seven

1. 01Standing AssertionA resting state is re-sent on a timer, because both ways it can be lost are silent.
2. 02Verified PresenceAn indicator asserts only what it has actually checked.
3. 03Closed VocabularyThe agent names a state; unsafe output is inexpressible rather than rejected.
4. 04Deference at RestA person acting on the device overrides the agent; the agent notices only at rest.
5. 05One Ordering, One PlaceSingle-channel, so precedence is the design, and it must live in one place.
6. 06Darkness as AlarmKeep the resting state lit, so going dark can mean one thing.
7. 07Cap the DecorationCap decorative output by context; never cap a status signal.

Which paper is canonical

In OM-004 · Ambient Signals, and Revised Output, which is canonical for them. Every entry here is reproduced from it in full and links back to it. The paper is where they are written, and where a correction lands. Four of the seven carry an explicit note that something in them is untested — one has never been confirmed against a real hand on the device, one has never been observed at the hour it exists for, and one is contradicted by the implementation it was drawn from.

Inside one exchange, before it settles. Output that is rewritten after it has been shown.

Streaming ordinarily means output arriving incrementally. These seven are about output being revised after a person has already read it — a harder thing to display honestly, and much harder to display honestly at speed.

This is the finest grain in the catalogue. Where One Agent begins at the moment a turn is submitted and assumes a completed input and a bounded reply, these sit underneath that: the input is still being formed, the machine is already responding, and both are changing at once.

The seven

1. 01Draft and RecordOne pass to show, one pass to keep, and never let the first become the second.
2. 02No Frozen PrefixNo depth and no age at which freezing what is shown is safe.
3. 03Show the HandoverDraft errors get blamed on the system unless the seam is visible.
4. 04Churn Is Not CorrectionRepresent everything; present selectively. Oscillation is not information.
5. 05Deterministic Last MileThe last corrections are convention, not accuracy, so use a table.
6. 06One List, Two UsesOne vocabulary, read by the thing that hears and the thing that writes.
7. 07Draft and Record ApartSeparate storage, or the cheap pass becomes authoritative by accident.

Which paper is canonical

In OM-004 · Ambient Signals, and Revised Output, which is canonical for them. Every entry here is reproduced from it in full and links back to it. The paper is where they are written, and where a correction lands. Two of the seven have had their reference instance proposed for deletion by the same evidence that verified them — the patterns survive, the exemplar does not, and saying so is what the paper's added field exists to enforce.

Orientation · Pattern 1

Capability Disclosure

Intent

Make the agent’s powers, position and limits legible before the person commits to a request, so expectations are formed from evidence rather than optimism.

Also known as

Onboarding Surface; Working-Context Banner; Affordance Advertisement.

Motivation

A person opens a terminal agent and types “fix the tests.” The agent can read files, run commands and edit code, but it is rooted in the wrong directory, has no network access, and is looking at a different branch than the person assumes. Every one of those facts is knowable at startup. None is shown. The failure surfaces ten minutes later as a confusing wrong answer, and the person blames the model’s intelligence rather than its position.

Disclosure is not a help screen. A help screen answers what commands exist; disclosure answers what is true right now.

Applicability

Use when effective capability varies by context (directory, credentials, connected services, mode); when the cost of a wrong assumption is paid late; or when one surface serves people with different mental models.

Structure

Participants

Agent resolves and states its own position. Environment supplies ground truth. Person calibrates.

Collaborations

Feeds Mode Visibility (2), disclosure of the variable most likely to change underfoot. Weak disclosure increases load on Assume or Ask (5), because the agent must ask about things it could have stated.

Consequences

• Gain: mis-scoped requests are prevented instead of debugged.
• Gain: the person’s model stays accurate as context changes.
• Cost: screen real estate. Disclosure that scrolls past unread is decoration.
• Cost: it must be derived, never authored. A hand-written capability list is a lie with a delay fuse.

Implementation

Derive every disclosed fact from the live system. Prefer a persistent, low-noise surface over a one-time splash. Disclose limits alongside powers: “no network” is more useful than ten available tools. When a disclosed fact changes mid-session, say so; an unannounced change is worse than never disclosing.

Sample interaction

organon-one · master · claude-opus-5
tools: read, write, bash, powershell   ·   no network
⚠ this is a git worktree — added directories are not inherited

> fix the failing test

Failure signature

The person periodically asks questions whose answers the system already knows: “are you in the right folder?”, “can you see the database?” Repeated orientation questions are the tax on absent disclosure.

Known uses

Claude Code’s startup banner. Cursor’s workspace indicator. git status, the oldest and still one of the best capability-disclosure surfaces in software, worth studying because it is not conversational.

Related patterns

Mode Visibility (2) is its highest-frequency special case. Honest Gauge (12) governs its correctness.

Reproduced from OM-001 · the canonical entry, which this catalogue does not replace.

Orientation · Pattern 2

Mode Visibility

Intent

When a surface has modes that change the meaning of the same input, make the active mode visible at the moment of use, not merely settable at the moment of configuration.

Also known as

Modal Feedback; Mode Indicator; State Visibility.

Motivation

A push-to-talk surface has two modes: dictation, where speech becomes text at the cursor, and agent, where speech goes to an assistant who answers aloud. The mode is chosen from a menu and persists. A person who left it in dictation, then returns expecting conversation, holds the key, speaks, and gets text pasted into a code fence. Nothing errored. Everything worked. The system is behaving perfectly and appears broken.

The sharper version, observed directly: the same binary exposes --tray (icon, overlay, push-to-talk) and --listen (identical capture loop, no interface at all). Launched with the wrong flag, the voice loop works flawlessly and the entire visible interface is absent: a failure that reads as “the UI is broken” and means “you asked for the headless mode.”

Applicability

Whenever identical input produces materially different effects depending on state; when a mode persists across sessions; or when a mode is set in one place and used in another.

Structure

Participants

Mode is the hidden variable. Input is ambiguous without it. Indicator resolves the ambiguity where the input is given.

Collaborations

A special case of Capability Disclosure (1) with a much higher refresh rate. Where modes carry different blast radii, Approval Gate (10) should key off the mode, not merely the action.

Consequences

• Gain: the class of bug where “it works but appears broken” disappears.
• Cost: an indicator at the point of use competes for the most valuable space on the surface.
• Trap: the test is whether the person sees it while acting, not whether it exists.

Implementation

Bind the indicator to the same state the behaviour reads from, never a parallel copy. Prefer encoding mode in a channel the person already attends to: the cursor, the prompt, the colour of the thing they are holding. Where a mode defaults at startup to something other than last-used, say so loudly; silently reverting to a default is the most common instance of this failure.

Sample interaction

◉ AGENT   hold the chord, speak — she answers aloud
○ dictate hold the chord, speak — text lands at your cursor
          ^ shown in the overlay while you hold, not only in a menu

Failure signature

“It stopped working” for a system that is fully operational. Reports that cannot be reproduced by the maintainer, because the maintainer’s mode differs.

Known uses

vim’s -- INSERT --. Caps-lock indicators. Cursor’s agent/ask toggle. Terminal agents that print the active model in the prompt.

Related patterns

Capability Disclosure (1), Honest Gauge (12).

Reproduced from OM-001 · the canonical entry, which this catalogue does not replace.

Turn · Pattern 3

Streaming Turn

Intent

Emit the response as it is produced rather than when it is complete, so the person’s wait overlaps the agent’s work instead of following it.

Also known as

Incremental Rendering; Token Streaming; Progressive Response.

Motivation

A voice agent’s reply took 11.8 seconds from the end of the person’s speech to the first spoken word. Decomposed: roughly 7 seconds of model generation, then roughly 4.9 seconds of speech synthesis, strictly in series, because the synthesiser was handed the reply only when the reply was finished. Neither component was slow for what it did. The architecture declined to overlap them.

The fix is not optimisation. It is refusing to treat “the response” as an atomic object. Once the response is a stream of complete-enough fragments, synthesis of sentence one proceeds while sentence two is still being written. Measured on the same system after the change: the first speakable sentence was available at +1.14 s where the previous path returned nothing until +3.94 s.

Applicability

Use when generation is incremental and a downstream stage can begin on a prefix; when perceived latency matters more than total latency. Do not use when the consumer cannot act on a prefix without risk of acting on a fragment the remainder contradicts.

Structure

Participants

Producer emits fragments. Splitter decides what constitutes a complete-enough fragment. Consumer acts on each in order.

Collaborations

Makes Barge-In (4) meaningful: there is nothing to interrupt until something has started. Tool events from Tool-Call Transparency (8) belong in the same stream, in order.

Consequences

• Gain: perceived latency collapses toward the cost of the first fragment.
• Gain: the person can begin evaluating early, and interrupt as soon as they have seen enough.
• Cost: fragment boundaries become a design surface with their own failure modes. Too small starves the consumer; too large reintroduces the stall.
• Cost: partial output may be contradicted by what follows.
• Trap: the invariant is that streaming changes only when content appears, never what it is. This is testable and should be tested: streamed fragments concatenated must equal batched output, across arbitrary boundaries down to one character.

Implementation

Keep fragmentation policy at the consumer, which alone knows its own costs; a producer that guesses chunk sizes will drift from the consumer that measures them. Negotiate streaming explicitly (a header, a capability flag) so a non-streaming consumer still works and the change reverts without a rebuild. Hold fragments back across structures meaningless in half: code fences, quotations, negations.

Sample interaction

[+0.28s] {"type":"transcript","text":"…","stt_ms":260}
[+0.59s] {"type":"delta","text":"Yes, that's the swap unit."}
[+1.29s] {"type":"delta","text":" It was reporting failed while swap was active,"}
[+1.99s] {"type":"tool","on":true,"name":"bash"}
[+2.69s] {"type":"delta","text":" which is worse than cosmetic."}
[+3.39s] {"type":"end","reply":"Yes, that's the swap unit. It was …"}

Failure signature

A progress spinner with no content behind it. A response arriving all at once after a pause whose length correlates with the answer’s length: the signature of a system paying for its own verbosity before showing any of it.

Known uses

ChatGPT and Claude token streaming. Compiler diagnostics per file. git clone progress. A sentence pipeline that streams to a synthesiser instead of a screen.

Related patterns

Barge-In (4), Tool-Call Transparency (8).

Reproduced from OM-001 · the canonical entry, which this catalogue does not replace.

Turn · Pattern 4

Barge-In

Intent

Let the person seize the turn at any moment, and say what that stops.

Also known as

Interrupt; Cancel; Stop Generation; Push-to-Talk Override.

Motivation

The agent is thirty seconds into explaining something the person understood at second three. Without interruption the only options are to wait or kill the session, and both teach the person to ask smaller questions than they have. Interruption is not a convenience; it is what makes it safe to let the agent try.

But interruption has a scope, and the scope is usually misrepresented. Stopping audio is not stopping thought. Stopping the display is not stopping the tool call already writing to disk. A system that says “stopped” while a turn continues in the background has lied about the one thing the person was trying to control.

Applicability

Any surface with long-running output. Essential where output is time-based (speech, animation) and the person cannot skim ahead.

Structure

Participants

Person seizes. Turn is relinquished. Cancellation scope is the contract about what ceased.

Collaborations

Depends on Streaming Turn (3). Constrains Recoverable Execution (13): whatever cannot be stopped must be undoable.

Consequences

• Gain: the person lets the agent attempt more, because attempts are cheap to abandon.
• Gain: one motion (interrupt and redirect) beats stop, wait, retype.
• Cost: cancellation must thread through every layer, including ones that do not naturally support it.
• Trap: partially-completed side effects. An interrupted turn that wrote three of five files has left the world in a state nobody designed.

Implementation

Make the interrupt the same gesture as the next request where possible. Check cancellation at every stage boundary, and discard queued work instead of hiding it. Generating speech nobody will hear wastes the resource that made the system fast. State the scope in the person’s language.

Sample interaction

← agent: The swap unit was reporting failed while swap was actually
         active, which is worse than cosmetic because —
[person holds the chord]
  ⏹ audio stopped (18 ms) · turn still completing in background
◉ listening…

Failure signature

People waiting out responses they stopped reading. Or killing and restarting the process to regain control: the strongest possible signal that interruption is absent or untrusted.

Known uses

ChatGPT’s stop button. Claude Code’s Esc. Voice assistants’ wake-word barge-in. A cancellation predicate threaded through a synthesis pipeline and checked at every chunk boundary.

Related patterns

Streaming Turn (3), Recoverable Execution (13).

Reproduced from OM-001 · the canonical entry, which this catalogue does not replace.

Intent · Pattern 5

Assume or Ask

Intent

Ask exactly one high-value question when ambiguity would change the blast radius; otherwise proceed on a stated assumption.

Also known as

Clarifying Question; Disambiguation Turn; “scope services when in doubt.”

Motivation

Two failure modes bracket this pattern, and most systems pick one and suffer it. The over-asking agent confirms everything, and the person learns to skim and approve blindly, destroying the value of the questions that mattered. The under-asking agent guesses silently, and is right often enough that the one time it deletes the wrong branch is a genuine shock.

The resolution is not “ask when uncertain.” It is ask when uncertainty changes what can be damaged. Ambiguity about formatting is not ambiguity about which database.

Applicability

When multiple readings lead to materially different work; when the cheap reading is reversible and the expensive one is not; when a read-only inspection could resolve the ambiguity without asking at all.

Structure

Participants

Request carries the ambiguity. Blast-radius estimate is the decision function. Inspection is the preferred resolution. Question is the fallback.

Collaborations

Where the answer determines authority rather than direction, escalate to Approval Gate (10). Options offered should follow Constrained Choice (6).

Consequences

• Gain: questions become rare and therefore heeded.
• Gain: the person’s attention goes to decisions only they can make.
• Cost: requires a blast-radius model: real engineering, not a prompt.
• Trap: asking what the agent could have discovered by looking.

Implementation

Prefer inspection to interrogation. When you must ask, ask once, with concrete alternatives and a recommendation. Do everything that does not depend on the answer first, so the question arrives alongside progress. Reserve blocking questions for cases where proceeding under any assumption would be unsafe or would waste the work.

Sample interaction

> deploy the new build

Two readings, and they differ in what they touch:
  · staging    — reversible, no customer traffic
  · production — irreversible for ~4 min, customer-visible

I've built and tested the artifact (common to both). Which target?

Failure signature

Confirmation fatigue: the person answers “yes” without reading. Or its opposite: a class of incident whose post-mortem always begins “it assumed I meant…”.

Known uses

Microsoft’s HAI Guideline 8, “scope services when in doubt.” rm -i. Package managers that show a resolution plan before acting.

Related patterns

Constrained Choice (6), Approval Gate (10).

Reproduced from OM-001 · the canonical entry, which this catalogue does not replace.

Intent · Pattern 6

Constrained Choice

Intent

When ambiguity is enumerable, offer the options as selectable structure rather than inviting free text.

Also known as

Quick Replies; Suggestion Chips; Numbered Options; Slot Filling.

Motivation

“How would you like me to handle the migration?” costs the person a paragraph to answer and the agent another turn to interpret. If there are three viable approaches, saying so, and letting one be chosen, converts an essay into a keystroke and removes the interpretation step entirely.

This is where conversational purism does damage. Natural language is the right input for expressing intent; it is a poor input for selecting among known alternatives. Modern practice is explicitly hybrid.

Applicability

When the option set is known, small (two to five), and clearly exclusive or multi-select. Not when the set is long, when the person’s own framing carries information you would discard, or when options would prematurely narrow a genuinely open question.

Participants

Option set is finite. Recommendation carries the agent’s judgement. Escape hatch preserves free text for the case you did not anticipate.

Collaborations

Supplies the presentation layer for Assume or Ask (5) and Approval Gate (10).

Consequences

• Gain: the cost of answering drops to near zero.
• Gain: the agent receives an unambiguous token instead of prose to parse.
• Cost: enumerating is a commitment; a missing option becomes the agent’s fault, not the person’s oversight.
• Trap: options that overlap. Three phrasings of one action read as a system pretending to consult.

Implementation

Always include an escape to free text. Order by recommendation and say which is recommended and why. Make the consequences of each option visible in the option itself: the person chooses from the list, and reads nothing else.

Sample interaction

Where should this start?

  1  Streaming the reply  (recommended) — biggest measured win, ~11.8s → ~3s
  2  Verify the chord first — 30 seconds of your time, gates everything else
  3  The small true things — four closures, all reversible

  …or tell me something else.

Failure signature

Long person replies mostly re-stating options the agent already had. Repeated clarification loops on the same axis.

Known uses

Slack’s interactive messages. Claude Code’s permission prompt: allow once, allow always, deny. git rebase -i’s verb list.

Related patterns

Assume or Ask (5), Approval Gate (10).

Reproduced from OM-001 · the canonical entry, which this catalogue does not replace.

Execution · Pattern 7

Plan, Approve, Execute, Receipt

Intent

Structure delegated work as four distinct phases so that understanding, consent, action and evidence are each separately inspectable.

Also known as

Propose-Confirm-Act; Dry-Run-Then-Apply; The Agent Loop.

Motivation

The two degenerate forms are familiar. An agent that acts immediately produces work the person must audit after the fact, when the cost of being wrong has already been paid. An agent that only proposes produces documents the person must execute themselves, which is most of the work.

The pattern’s real content is where the seam goes. Approval after planning but before execution is the only position where the person’s judgement is both informed and still useful. Approval sought before a plan exists asks for consent to an unknown; approval sought after execution is not approval.

The fourth phase is the one most often dropped. A receipt (what happened, as distinct from what was planned) is what makes the next turn honest.

Applicability

Any multi-step task with side effects. Scale ceremony to blast radius: a reversible one-step change needs no plan document, and the pattern degrades gracefully to “act, then receipt.”

Structure

Participants

Plan is an editable artifact. Gate is the consent boundary. Trace is live evidence. Receipt is durable evidence.

Collaborations

The gate is Approval Gate (10), placed by Progressive Autonomy (11). The trace is Tool-Call Transparency (8). The receipt feeds Durable Memory (14).

Consequences

• Gain: review happens when it can still change the outcome.
• Gain: plans become reusable, quotable, correctable artifacts.
• Cost: four phases on trivial work is bureaucracy that trains people to skip the phases on non-trivial work.
• Trap: a receipt that restates the plan instead of reporting reality.

Implementation

Let the plan be edited in place, not rejected and regenerated. Report divergence loudly. Never mark a step complete on the basis of having started it: record the artifact, not the intent.

Sample interaction

PLAN
  1  commit 13 files to the working branch
  2  merge to master (branched off master — not stacked)
  3  rebuild in the main checkout        ← durable path, not the worktree
  4  re-point the login shim             ← standing change, survives reboot
  none of these need elevation.

> go

RECEIPT
  ✓ 1  b9574b2 · 13 files, +1036 −135
  ✓ 2  870e197 · merged, pushed to origin
  ✓ 3  rebuilt · warnings only
  ✓ 4  shim now points at the main checkout
  ⚠ noted: one directory left untracked — your call, not mine

Failure signature

The person reads diffs after the fact to discover what was done. “What did you change?” asked after an agent turn is the diagnostic.

Known uses

Terraform’s plan / apply. Claude Code’s plan mode. Aider’s diff-then-commit. apt’s package plan.

Related patterns

Approval Gate (10), Tool-Call Transparency (8), Recoverable Execution (13).

Reproduced from OM-001 · the canonical entry, which this catalogue does not replace.

Execution · Pattern 8

Tool-Call Transparency

Intent

Expose which tool ran, against what target, why, and with what result. Give it as structured events, not as prose and not as raw reasoning.

Also known as

Activity Trace; Tool Receipt; Action Log.

Motivation

An agent that says “I checked the configuration” has told the person nothing checkable. An agent that shows the command and its output has told them something they can verify, correct and reuse. The difference is not verbosity; it is whether the claim is anchored.

The boundary matters in both directions. Exposing the tool call is necessary. Exposing raw chain-of-thought is neither necessary nor generally desirable: it is long, it is not a commitment, and treating it as one trains people to audit the wrong artifact. What the person needs is the action, its target and its result.

Applicability

Whenever a tool has effects outside the conversation, or whenever a claim in the response depends on something the agent observed.

Structure

Participants

Tool event carries intent, target and result as structure. Claim in the prose references the event.

Collaborations

Rides the channel of Streaming Turn (3), in order. Feeds Ambient Activity Channel (9) and Recoverable Execution (13).

Consequences

• Gain: claims become verifiable, errors locatable.
• Gain: the person learns what the system can do instead of guessing at it.
• Cost: volume. Forty tools produce forty events, and an undifferentiated wall of them is its own opacity.
• Trap: showing the call but not the result.

Implementation

Emit tool activity as typed events in the response stream, not as text the model composed: a model describing its own tool use can be wrong about it. Collapse routine reads by default; expose writes always. Make targets addressable (file:line) so the trace is a navigation surface, not just a record.

Sample interaction

⏺ Bash · why: confirm the renderer's bind address
  grep -rn "bind" services/lighting/src/main.rs
  → main.rs:508  UdpSocket::bind(SocketAddr::from(([127,0,0,1], port)))

  Loopback only — so the sandbox cannot reach it. That rules out
  the direct route.

Failure signature

The person cannot tell whether the agent looked or is recalling. Claims that turn out to be plausible reconstructions of files never read.

Known uses

Claude Code’s tool-call cards. Cursor’s file-edit list. Devin’s terminal pane. CI logs, the pre-agent ancestor of the whole pattern.

Related patterns

Ambient Activity Channel (9), Honest Gauge (12).

Reproduced from OM-001 · the canonical entry, which this catalogue does not replace.

Execution · Pattern 9

Ambient Activity Channel

Intent

Signal the agent’s state through a channel the person perceives without attending to it, so presence and progress cost no screen and no focus.

Also known as

Peripheral Awareness; Presence Layer; Calm Signalling.

Motivation

A person who delegates a two-minute task does one of two things: watches the transcript, which wastes the delegation, or leaves, which means discovering the outcome late. Both are bad, and the on-screen middle ground (spinners, progress bars) still demands the eye.

Peripheral channels solve this. A lamp that reads violet while the agent thinks, cyan while it runs a tool, warm while it speaks and amber while it waits for consent conveys state continuously to someone looking at something else entirely. It costs no pixels, competes with no content, and is legible across a room.

The distinction that makes this a pattern: the channel reports state, never instructions. The renderer is told what is happening and decides what that looks like, so the palette can be retuned without touching the agent.

Applicability

When tasks are long enough to walk away from; when attention is elsewhere; when a peripheral channel exists. Especially valuable where the agent has no visible surface at all: headless or voice-first systems.

Structure

Participants

State events are semantic. Renderer owns presentation and a priority stack. Device is peripheral. Person perceives without attending.

Collaborations

Consumes Tool-Call Transparency (8) events. Must obey Honest Gauge (12): a peripheral signal that lies is worse than a transcript that lies, because it is trusted without being read.

Consequences

• Gain: presence at zero attentional and zero screen cost.
• Gain: otherwise-invisible states become legible: a tool-heavy turn returning no text.
• Cost: a second rendering surface to keep true, on a channel with no error reporting.
• Cost: ambiguity. More than about six states is a colour-memory quiz.
• Trap: network topology. A sandboxed agent often cannot reach a host-loopback renderer.

Implementation

Send state, not presentation. Give every state a time-to-live so a lost “off” decays rather than stranding the device. Establish a priority order, so that a failure interrupts a completion flourish instead of queueing behind it. Make the channel opt-in and fire-and-forget: a lamp must never block the path that captures audio or applies a patch.

Sample interaction

{"t":"listening","on":true}                 → teal, rising
{"t":"thinking","on":true}                  → violet, slow drift (never repeats)
{"t":"tool","on":true,"name":"bash"}        → cyan, crisper scan
{"t":"speaking","on":true,"ms":4200}        → warm white, speech cadence
{"t":"error","msg":"agent unreachable"}     → red, brief, then decays

Failure signature

The person watches a transcript for a task they had delegated. Or, revealingly, asks “is it still going?” That is the question a peripheral channel exists to make unnecessary.

Known uses

Build-status lamps and CI orbs. IDE gutter activity indicators. The terminal bell on completion. Networked lamps driven from a voice agent’s turn lifecycle.

Related patterns

Tool-Call Transparency (8), Honest Gauge (12), Mode Visibility (2).

Reproduced from OM-001 · the canonical entry, which this catalogue does not replace.

Authority · Pattern 10

Approval Gate

Intent

Require explicit, per-action consent before any step that is irreversible, outward-facing, or spends the person’s authority in a way they would want to know about.

Also known as

Confirmation; Permission Prompt; Human-in-the-Loop Checkpoint.

Motivation

Delegation is not transfer. A person who says “clean up the old branches” has delegated judgement about which branches, not authority to force-delete on a shared remote. The gap between those is where every agent horror story lives.

The difficulty is that gates are expensive: each costs attention, and attention spent on a low-stakes gate is unavailable for a high-stakes one. A system that confirms everything has, in practice, confirmed nothing.

The organising principle is reversibility, not danger. A frightening-sounding but trivially revertible action needs no gate. A boring-sounding one that sends mail to a customer needs one, every time.

Applicability

Gate: irreversible deletion, outward-facing communication, spending money, publishing, granting access, changing standing configuration that outlives the session. Do not gate: reads, reversible local edits under version control, anything covered by a broader consent given knowingly.

Structure

Participants

Blast-radius test decides. Gate names the specific effect. Consent is per-action and does not generalise.

Collaborations

Positioned by Progressive Autonomy (11), presented via Constrained Choice (6), made cheaper by Recoverable Execution (13): the more that is undoable, the fewer gates are needed.

Consequences

• Gain: the person retains authority over exactly the actions carrying it.
• Gain: gates are rare enough to be read.
• Cost: latency at the moments the person is least present.
• Trap: consent laundering: approval obtained once, in one context, silently reused in another.
• Trap: a gate that cannot be satisfied. If the agent lacks the capability anyway, asking is theatre.

Implementation

Name the specific effect, not the category: “push to origin/master, force” rather than “perform a git operation.” Where the agent genuinely cannot act (an unelevated shell facing a root-owned unit), do not route around it; say plainly that a prompt is coming, what it is for, and hand over the exact command. Make refusal cheap: offer the nearest reversible thing instead of stopping dead.

Sample interaction

This one needs your password — sudo is not passwordless here, and a
capability must never sit on a hidden prompt.

    sudo systemctl restart organon-vera

It reloads the rewritten extension. Her memory carries; only live
context is lost. I'll wait — nothing else I'm doing depends on it.

Failure signature

People discovering completed actions they would have declined. Or the inverse: a confirm dialog answered reflexively, which means the gate has become furniture.

Known uses

Claude Code’s permission modes. sudo. OAuth consent screens. Deployment approvals in CI. git push --force-with-lease as a gate encoded in a flag.

Related patterns

Progressive Autonomy (11), Assume or Ask (5), Recoverable Execution (13).

Reproduced from OM-001 · the canonical entry, which this catalogue does not replace.

Authority · Pattern 11

Progressive Autonomy

Intent

Let the scope of unattended action widen with demonstrated reliability and narrow with risk, rather than fixing it once at design time.

Also known as

Autonomy Budget; Trust Ladder; Supervised → Autonomous.

Motivation

A single autonomy setting is wrong in both directions. Set conservatively, the agent asks permission to read a file for the thousandth time. Set permissively, it inherits authority over actions the person never considered.

Autonomy is better modelled as a ladder whose rungs are defined by reversibility, and on which position is negotiated: the person grants a rung for a session, a repository or a class of action, and the agent falls back a rung when it meets something it did not anticipate.

Applicability

Where one agent performs work spanning several orders of blast radius; where a long session would otherwise accumulate identical prompts; where different contexts warrant different defaults.

Structure

Participants

Rungs defined by reversibility. Grant has scope and expiry. Fallback is automatic on surprise.

Collaborations

Determines where Approval Gate (10) sits. Depends on Recoverable Execution (13) to make middle rungs safe.

Consequences

• Gain: prompt volume falls without authority quietly expanding.
• Gain: one agent is usable in a scratch repo and against production.
• Cost: the rung model must be explicit and legible, or it becomes invisible policy.
• Trap: ratchets. Autonomy that only ever increases is a slow-motion incident.

Implementation

Define rungs by reversibility. Scope grants explicitly (this session, this repo, this class), and show the current rung as part of Capability Disclosure (1). Fall back automatically when something unanticipated appears, and say that you did.

Sample interaction

Working at rung 3 — reversible writes, this repo, this session.

  ⚠ dropping to rung 2: the change touches the login shim, which
    outlives the session. Standing configuration is a gate, not a write.

  Here is the diff. Say go and I'll apply it.

Failure signature

Long sessions accumulating identical approvals. Or permissions that, once granted, are never revisited even as the work moves from a sandbox to something real.

Known uses

Claude Code’s plan mode → accept-edits → bypass ladder. sudoers scoping. CI environments with per-branch deploy rights.

Related patterns

Approval Gate (10), Capability Disclosure (1).

Reproduced from OM-001 · the canonical entry, which this catalogue does not replace.

Truth and continuity · Pattern 12

Honest Gauge

Intent

Ensure every status signal is wrong only when the system is wrong; a signal that reports failure in its healthy steady state destroys its own value on the day it is right.

Also known as

Alarm Fatigue Avoidance; Signal Integrity; Meaningful Red.

Motivation

A oneshot service activates a swapfile at boot. Its ExecStart ran a bare swapon, which exits 255 with “Device or resource busy” when the swapfile is already active. So the unit recorded a failure for a job with nothing left to do, and the machine’s status surface reported organon-swap: failed while 27 GB of swap was demonstrably working.

The cost is not cosmetic. That red is indistinguishable from the red meaning swap genuinely failed to activate: the exact condition the unit exists to prevent, whose real symptom is a 21 GB model load killed by the OOM reaper, and which is expensive to diagnose from the other end. A gauge that always reads red tells you nothing on the day it is right.

The same session produced the other half: a command surface built specifically to make traps visible was itself blind to the newest service, because the service was added and the surface was never told. A gauge can lie by commission or by omission.

Applicability

Every status surface: service states, health checks, test suites, dashboards, and above all peripheral channels (pattern 9), which are trusted without being read.

Structure

Participants

Gauge reports. Healthy steady state must map to OK. Person must be able to act on the difference.

Collaborations

Governs Capability Disclosure (1), Mode Visibility (2) and Ambient Activity Channel (9). Undermines Approval Gate (10) when violated: a gate whose stated effect comes from a lying gauge obtains uninformed consent.

Consequences

• Gain: a signal that is acted upon.
• Cost: idempotency is real work. Distinguishing “already done” from “could not be done” often requires a check the naive command does not perform.
• Trap: gauges never re-examined after the system around them changes. Most dishonest gauges were honest when written.

Implementation

Make the healthy steady state exit zero, explicitly: guard the action instead of assuming a fresh system. Treat adding a component without teaching the status surface about it as an incomplete change. The surface is part of the component. Re-verify gauges whenever the thing they measure changes shape.

Sample interaction

# Before — red in its healthy state
ExecStart=/sbin/swapon /swapfile
  → swapon: /swapfile: swapon failed: Device or resource busy
  → status=255/EXCEPTION · unit: failed      (swap: 27 GB active)

# After — red means red
ExecStart=/bin/sh -c 'if swapon --show=NAME --noheadings | grep -qx /swapfile; \
                      then echo "/swapfile already active"; \
                      else exec swapon /swapfile; fi'
  → /swapfile already active
  → Finished · unit: active                  (swap: 27 GB active)

Failure signature

A known-bad indicator everyone has learned to ignore. The sentence “oh, that’s always red” is the pattern’s absence, stated aloud.

Known uses

Idempotent health checks. Configuration management’s converge-to-desired-state model. Flaky-test quarantine, which exists because a suite that is always red is not a suite.

Related patterns

Capability Disclosure (1), Ambient Activity Channel (9).

Reproduced from OM-001 · the canonical entry, which this catalogue does not replace.

Truth and continuity · Pattern 13

Recoverable Execution

Intent

Ensure every action has a visible before-state and a path back, so that being wrong is cheap.

Also known as

Undo; Checkpoint; Diff-Before-Apply; Rollback.

Motivation

Recoverability is what makes every other pattern affordable. Approval Gate (10) can be rare only because ungated actions are reversible. Progressive Autonomy (11) can climb only because the middle rungs are safe. Barge-In (4) is only safe when a half-finished turn can be unwound.

The corollary is the design rule: the ceremony an action needs is inversely proportional to how easily it can be undone. Invest in reversibility and you buy down the interaction cost of everything else.

Applicability

All state-changing work. Especially where the agent operates faster than the person can review — the normal case.

Structure

Participants

Before-state is captured before acting, not reconstructed after. Diff is the reviewable artifact. Restore returns without losing the task.

Collaborations

Reduces the gates Approval Gate (10) needs. Enables Progressive Autonomy (11). Its evidence is Tool-Call Transparency (8).

Consequences

• Gain: exploration becomes cheap, which is the point of delegation.
• Gain: review shifts from prose to diffs: precise and skimmable.
• Cost: capturing before-state has real overhead.
• Trap: the irreducible set: sent mail, published posts, deleted remote branches, spent money. These cannot be made reversible, which is why they must be gated.

Implementation

Prefer the substrate’s own mechanisms (version control, transactions, snapshots) over bespoke undo stacks. Capture before-state at the boundary of the action, not the session. Make the diff the primary review surface. For genuinely irreversible steps, be explicit that this is where recoverability ends; that is what elevates them to gates.

Sample interaction

Applied to 3 files · nothing committed yet

  chord.rs      +18 −6      default chord → Ctrl+Win
  main.rs       +4  −2      derive the label instead of hardcoding it
  GUIDE.md      +9  −6      the docs said Alt+Win; they were stale

  [d] review diff   [k] keep   [u] undo all   [c] commit

Failure signature

People copying files aside before letting the agent work. Manual backups are the tax on absent recoverability, and a precise measure of how much the agent is trusted.

Known uses

Git as the universal substrate. Cursor’s checkpoint-and-restore. Aider’s per-change commits. Database transactions.

Related patterns

Approval Gate (10), Progressive Autonomy (11), Barge-In (4).

Reproduced from OM-001 · the canonical entry, which this catalogue does not replace.

Truth and continuity · Pattern 14

Durable Memory

Intent

Carry what matters across sessions in durable, inspectable memory rather than in the length of a transcript, so restarting is cheap and context becomes a chosen artifact, not an accident of scrollback.

Also known as

Working Memory; Persistent Context; Project Memory; Compaction.

Motivation

Two failure modes again bracket the pattern. Systems that keep everything drown: context fills with resolved detail, signal-to-noise falls, cost rises. Systems that keep nothing make every session begin with re-explanation, which teaches people to keep sessions alive far past their useful life, hoarding a transcript as a substitute for memory.

The reframing: continuity is memory, not session length. If durable memory is good, restarting is a normal operation rather than a loss. If it is bad, no session is ever long enough.

Applicability

Any agent used repeatedly against the same project; essential where the agent is a long-lived service, not a session.

Structure

Participants

Transcript is ephemeral. Memory is durable and editable. Promotion decides what crosses. Correction keeps memory true.

Collaborations

Fed by the receipts of Plan, Approve, Execute, Receipt (7). Governed by Honest Gauge (12): stale memory is a lying gauge with a long half-life.

Consequences

• Gain: restarting is normal, which makes upgrades, crashes and context limits non-events.
• Gain: the person can read and correct what the agent believes.
• Cost: promotion is a judgement call, and both over- and under-promotion have real costs.
• Trap: stale memory is worse than none. A memory recording a keybinding that has since changed will actively mislead.
• Trap: memory that records what without why. The reason is the part that survives contact with a changed system.

Implementation

Promote decisions, constraints and hard-won traps; let resolved detail go. Record the why, and prefer absolute dates to relative ones. Make memory a first-class artifact, not a hidden embedding: something the person can read, edit and delete. Re-verify on read: if a memory names a file, flag or key, confirm it still exists before acting on it. When a fact changes, correct the memory in the same motion as the change, or the next session inherits the error with full confidence.

Sample interaction

CURRENT as of 2026-08-11 ~21:10 (merged 870e197, deployed from main)

  · Chord is Ctrl+Win. The competing tool is DISABLED — that is what
    freed it. Four chords were tried in one day; every move was forced
    by coexisting with that tool. Removing it solved the problem in one step.
  · ⚠ --tray is the flag, not --listen. --listen is headless: no icon,
    no overlay, everything else identical. Cost real debugging time.

(Chord history — superseded, see CURRENT above.)

Failure signature

People refusing to restart a degraded session because “it knows too much.” Or an agent confidently acting on a fact that was true last month.

Known uses

Project instruction files such as CLAUDE.md. Claude Code’s /compact. Cursor’s rules files. Architecture decision records, which are this pattern applied to teams rather than agents.

Related patterns

Plan, Approve, Execute, Receipt (7), Honest Gauge (12), Capability Disclosure (1).

Reproduced from OM-001 · the canonical entry, which this catalogue does not replace.

The split · Pattern 1

Proposed Dispatch

Intent

Let the context that already holds the work propose the units, so the person approves a decomposition rather than authoring one from memory.

Motivation

A person has been working with an agent for an hour. That agent knows the codebase, what has been tried, which constraint bit last time, and what the person actually meant three messages ago. Then the person opens a fresh window and types a new prompt, reconstructing by hand a fraction of what the agent already holds, and doing the decomposition themselves, badly, because splitting work well requires knowing all of it.

The expensive part of fan-out is not running the agents. It is deciding what the units are. Doing that in the party with the least context is the defect.

Applicability

When work decomposes into units that can run independently; when a primary agent holds context the person would otherwise restate; when the person's judgement is better spent on which and whether than on how to phrase it.

Structure

Participants

Primary agent proposes and states each unit's scope. Person approves, edits or refuses. Units carry the proposal forward as their commission.

Collaborations

Takes its form from Constrained Choice (OM-001 · 6): enumerated units, not free text. Approving one is Approval Gate (10) applied to a decomposition rather than an action. What it hands to Authority at Dispatch (2) determines whether the unit can be dispatched unattended at all.

Consequences

• Gain: the decomposition is done by the party with the most context.
• Gain: the person's contribution becomes taste and direction, which is the part only they have.
• Cost: a proposal is easy to approve without reading, and approving without reading automates the wrong half of the job.
• Trap: the agent proposing the work is also the one least able to see what it does not know. A decomposition can be internally perfect and miss a unit entirely.

Implementation

Propose units, not prompts, and make each editable in place. State each unit's scope on the proposal, so approval is informed by what it will be allowed to do rather than only by what it intends. Never dispatch on proposal; the pause is the pattern. Offer refusal as a first-class outcome: a decomposition the person rejects wholesale is a useful result, not a failure of the interaction.

Sample interaction

Suggested task
  Rename the shell to the console, safely
  SHELL_ARCHITECTURE.md becomes CONSOLE_ARCHITECTURE.md and the
  crate stops calling itself a shell — while leaving untouched the…

  [ Start with worktree ▾ ]   Start locally · Send to cloud · Fix here

Failure signature

The person retypes context the agent already had, at the top of every dispatch. Or: dispatched units that overlap or leave a gap, because the person who split them could not see the whole.

Known uses

Suggested-task surfaces that offer a worktree, a local run or a cloud run. Agents that file their own issues for later work. A planning step whose output is a list of separable jobs rather than prose.

Related patterns

Authority at Dispatch (2), Constrained Choice (OM-001 · 6), Approval Gate (OM-001 · 10).

Reproduced from OM-002 · the canonical entry, which this catalogue does not replace.

The split · Pattern 2

Authority at Dispatch

Intent

Grant a dispatched agent its authority once, at dispatch, in a form the environment enforces, because per-action approval does not survive more than one agent.

Motivation

Approval Gate (OM-001 · 10) is the strongest pattern in the first language, and it works because the person is there. Consent is per-action, specific, and given with the argument in front of them.

Now dispatch twelve agents. The person is present for at most one. The other eleven face a choice with no good branch: stop and wait for a human who is not coming, which destroys the reason for dispatching them; or proceed unapproved, which destroys the gate. No amount of prompt engineering resolves this, because it is not a phrasing problem. It is arithmetic.

So the gate moves. Authority is granted at the moment of dispatch, bounded to the unit, and enforced by something other than the agent's cooperation.

This is a real loss and should be stated as one. Dispatch-time authority is granted blind: a class of action is approved before any instance of it is seen. That is strictly less informed than Approval Gate. What buys it back is that the scope is narrow, mechanical, and cannot be talked out of.

Applicability

Whenever more than one agent runs without a human present. Also whenever a single agent runs long enough that the person will not be there for its middle.

Structure

Participants

Commission carries the scope. Environment enforces it. Unit acts freely inside it and cannot act outside it. Person grants once and is then absent.

Collaborations

Replaces Approval Gate (OM-001 · 10) for the common case and depends on it for the irreducible set. Its scope is usually realised by Isolation by Construction (3). Progressive Autonomy (OM-001 · 11) is how a scope widens over time, and is what stops this pattern being a permanent grant.

Consequences

• Gain: N agents run unattended without either stalling or running unbounded.
• Gain: the scope is inspectable before dispatch, which makes approval meaningful, not ceremonial.
• Cost: authority is granted before the action is known. This is the pattern's price and it is not recoverable by being clever.
• Cost: enforcement is real engineering. A scope nothing checks is a wish.
• Trap: a scope written in a prompt is not a scope. An instruction is a request to a system that is allowed to be wrong.

Implementation

Express scope as something the environment already enforces: a worktree, a branch, a directory, a token with narrow permissions, a container. Prefer scopes that make the dangerous action impossible to scopes that ask for restraint. Keep an irreducible set that no dispatch may pre-authorise: anything outward-facing, anything that publishes, anything that cannot be undone. Route those back to a live human even at the cost of the unit stalling. A unit stalled on a genuinely irreversible action is the system working.

Sample interaction

commission
  unit      fix the failing snapshot tests
  workspace .worktrees/snapshot-fix      (own branch, own checkout)
  may       read repo · write workspace · run tests
  may not   push · open PR · touch main · network
  escalate  anything outward-facing → back to a human

Failure signature

An agent sent to fix tests pushes to main. Or the mirror image, equally diagnostic: every dispatched agent is blocked on an approval nobody is present to give, and the team's throughput is zero while every unit reports itself healthy.

Known uses

CI job permissions and scoped tokens. sudoers. Container capabilities. Database roles. The narrowly-scoped deploy key that exists because nobody will be watching.

Related patterns

Isolation by Construction (3), Approval Gate (OM-001 · 10), Progressive Autonomy (OM-001 · 11).

Reproduced from OM-002 · the canonical entry, which this catalogue does not replace.

The split · Pattern 3

Isolation by Construction

Intent

Give each unit a workspace in which collision is impossible, so parallelism does not depend on the units being careful.

Motivation

Two agents in one checkout. The first moves a file; the second writes to where it used to be. Or both edit the same function and the later write wins silently. Nothing errors, both report success, and the result is a tree neither of them describes. The failure is not that the agents were careless — it is that carefulness was load-bearing.

The remedy is structural and old: give each unit its own copy. A git worktree, a container, a branch, a scratch directory. Collisions stop being unlikely and start being unrepresentable.

The second effect matters as much as the first: isolation is what makes the scope in pattern 2 enforceable. “May write its workspace” means something only if the workspace has edges.

Applicability

Whenever two or more units may touch the same artifacts. Especially where the shared artifact is a working tree, a database, a device, or a service that permits one caller.

Structure

Participants

Workspace is the unit's own. Result leaves it as a durable artifact: a branch, an image, a file. Join is where results meet, and the only place they may.

Collaborations

Realises the boundary Authority at Dispatch (2) declares. Its artifact is what The Return Path (6) carries and what Gather (8) reconciles. The workspace boundary is also the before-state Recoverable Execution (OM-001 · 13) needs: discarding a unit is discarding its workspace.

Consequences

• Gain: parallelism without coordination between units, which is the only kind that scales.
• Gain: a failed unit is discarded, not unwound.
• Cost: setup per unit, in time and disk. Real but small: a worktree costs a few hundred milliseconds and a copy of the tree.
• Cost: conflict is deferred, not removed, and arrives all at once at the join.
• Trap: isolation by convention. “The agents were told to work on different files” is not isolation; it is a hope with a schedule.

Implementation

Prefer the isolation the platform already has, because it is enforced, not simulated. Make the artifact the unit leaves a first-class thing with a name. A branch is better than a diff in a message, because it survives the conversation. Clean up automatically when a workspace is unchanged, or the mechanism accretes debris and people stop using it. And note the shared resources isolation does not cover: a port, a device, a bot token, a rate limit. Those need a mutex or a rule, and where no mutex exists the rule has to be stated, not assumed.

Failure signature

You are reluctant to run two agents at once, and cannot immediately say why. Or a change appears in the tree that no unit's report mentions.

Known uses

Git worktrees and branches. Containers. CI runners, one per job. Database transactions. Any build system with a per-target sandbox.

Related patterns

Authority at Dispatch (2), Gather (8), Recoverable Execution (OM-001 · 13).

Reproduced from OM-002 · the canonical entry, which this catalogue does not replace.

In flight · Pattern 4

Fire and Forget

Intent

Make a dispatch complete at the moment it is made, so the person can turn immediately to the next thing rather than staying to shepherd the last one.

Motivation

This is the pattern that makes every other one worth having, and it is best stated as the behaviour it enables:

“Dispatch an agent, then immediately get back to doing something else and dispatch another agent. And the whole time, you are giving the thing that the agents need, which is the taste and the direction and the choices that make this thing you're building yours.”

Now suppose each dispatch asks one clarifying question thirty seconds in. Nothing is broken; each question is reasonable; the agent is being careful. But the person cannot leave, so they cannot dispatch the next one, and throughput is pinned at one agent no matter how many the system can run. A dispatch you have to watch is a dispatch that cannot be followed by another.

The arithmetic is unforgiving. A unit that is ninety-five per cent unattended is not unattended; the five per cent lands on a single serialised human.

Applicability

Whenever the intended working rhythm is many dispatches in a session. Not applicable where a single unit genuinely warrants supervision: a migration, a destructive operation, anything the person wants to watch. Those are supervised runs, and calling them dispatches is the mistake.

Structure

Participants

Commission carries everything the unit needs. Unit proceeds on stated assumptions instead of stopping. Person leaves and does not return until the join.

Collaborations

Puts the whole weight on Assume or Ask (OM-001 · 5): a unit that cannot ask must be very good at deciding when ambiguity actually changes the blast radius, and at proceeding under a stated assumption when it does not. Depends on Authority at Dispatch (2), which is what makes proceeding safe. Status Board (5) is what lets the person leave without anxiety.

Consequences

• Gain: throughput scales with the person's dispatch rate, not their attention span.
• Gain: the person's contribution concentrates on direction and taste, which is where it is scarce.
• Cost: a unit that cannot ask must guess, and some guesses are wrong in ways discovered only at the join.
• Cost: assumptions must be recorded, or the join cannot tell a decision from an accident.
• Trap: one blocking question per unit reintroduces full serialisation. The cost is not proportional to how often it happens; a single question at the wrong moment stops the rhythm.

Implementation

Everything the unit needs travels with it at dispatch; a question it must ask is a defect in the commission, not a virtue in the agent. Where it genuinely must ask, prefer asking and continuing on a stated assumption to asking and stopping, and put the assumption in the report so the join can audit it. Give questions somewhere to accumulate that is not an interrupt, so the person answers a batch when they choose rather than a stream when they do not.

Failure signature

The person dispatches, then sits watching that unit until it finishes. Or, at the team scale, N agents all halted on questions and one person working through them in series — which looks like diligence and is a stall.

Known uses

Batch jobs with all inputs supplied up front. make -j. Anything designed to be run overnight, where asking is not an option and the design absorbed that constraint.

Related patterns

Status Board (5), Assume or Ask (OM-001 · 5), Authority at Dispatch (2).

Reproduced from OM-002 · the canonical entry, which this catalogue does not replace.

In flight · Pattern 5

Status Board

Intent

Show every unit's state on one surface, at the granularity the channel actually carries, and never at a granularity it does not.

Motivation

A dispatch card in a console sat on running for eight to sixteen minutes and then produced a wall of text. The events had been arriving the entire time and were being dropped on the floor. One reading covered every state from “just started” to “nearly done”, which is Honest Gauge (OM-001 · 12) at team scale: a gauge whose single value spans the range you needed it to distinguish.

Fixing it surfaced the harder half. The harness never forwards token-level deltas from a subagent. A dispatched agent's work arrives as completed bursts, and the gaps between them are real gaps, not rendering latency. So the honest surface reports counts, completed steps, the last tool, and elapsed time. It must not imply a liveness that does not exist. A blinking cursor there would be a lie the data cannot support, and it is exactly the lie a designer reaches for.

The third finding is a correlation trap worth stating because it fails silently: the lifecycle events key on task_id, not tool_use_id, and two of the five carry no tool_use_id at all. Keying on the obvious field drops every status transition while the surface continues to look like it is working.

Applicability

Any time more than about two units are in flight. Especially where units are long-running, where the person is deliberately absent, and where the only alternative is opening each session in turn to find out what happened.

Structure

Participants

Units emit whatever the harness forwards. Status Board aggregates without inventing. Person reads it at a glance and decides whether to intervene.

Collaborations

A direct application of Honest Gauge (OM-001 · 12); every rule there applies unchanged and matters more, because there are N of them. Ambient Activity Channel (OM-001 · 9) is how this reaches a person who is not looking at the screen. It is what makes Fire and Forget (4) psychologically possible.

Consequences

• Gain: the person dispatches more, because they can see more.
• Gain: a stuck unit is visible as stuck, not as slow.
• Cost: a second rendering surface that must be kept true as the team's shape changes.
• Cost: aggregate views hide individual detail by design, and sometimes the detail was the point.
• Trap: implying liveness the channel cannot support. This is the specific dishonesty available here, and it is attractive because the honest version looks less alive.

Implementation

Report exactly what the channel carries and label it as what it is: elapsed since the last event is not elapsed since the last work, and saying so costs one word. Verify the correlation key by measurement instead of by its name; the obvious field is sometimes absent from the events that matter most. Distinguish “no news” from “no progress”, because they look identical and mean opposite things. And prefer a surface that shows all units badly to one that shows one unit well, since the question being asked is nearly always about the set.

Sample interaction

team · 4 units
  01  snapshot-fix     running   7 steps   last Bash        4m12s
  02  docs-rename      running   3 steps   last Edit       11m03s   ← quiet 9m
  03  theme-extract    done      12 steps  branch ready     6m48s
  04  bench-sweep      halted    2 steps   awaiting a human  0m31s

Failure signature

“Is it still going?” asked about a team. Or a person opening each session in turn to find out what finished: the manual scan a status board exists to make unnecessary.

Known uses

CI dashboards. jobs and process supervisors. Build farm views. A console's subagent cards folded onto the card that spawned them.

Related patterns

Honest Gauge (OM-001 · 12), Ambient Activity Channel (OM-001 · 9), Fire and Forget (4).

Reproduced from OM-002 · the canonical entry, which this catalogue does not replace.

The join · Pattern 6

The Return Path

Intent

Route a completed unit's result back to the context that commissioned it, so no human has to carry it there.

Motivation

Four agents were dispatched overnight. In the morning all four had finished, each on its own branch. What happened next is the pattern's whole case:

“I gave them that prompt. And then I took all of the replies and pasted them in series back to the agent that dispatched them.”

A person performed message routing, by hand, with a clipboard. Every unit had succeeded. Every result existed. Nothing errored, and no system reported a problem, because from each unit's point of view there was none — the work returned, but it returned to the wrong place, and a human carried the last hop.

That is why this one is easy to miss for a long time. There is no error state, no red light, and no moment at which anything is obviously wrong. The entire cost is denominated in somebody's morning, and it scales linearly with the team.

A second, subtler failure hides underneath: the branch is not the report. A branch says where the work is. A report says what was done, what was assumed, what was refused, and what the next context needs to know. A team that leaves branches and no reports has produced artifacts nobody can act on without reading diffs.

Applicability

Whenever a unit's result must inform a context other than the person's own attention, which is nearly always, once a primary agent is doing the decomposition.

Structure

Participants

Commission carries the return address. Report is the account, distinct from the artifact. Artifact is the durable work. Commissioning context receives both without a human relay.

Collaborations

Feeds Gather (8), which cannot happen at all without it. Carries what Nested Attribution (7) requires. It is Plan, Approve, Execute, Receipt (OM-001 · 7)'s receipt, arriving from an actor who was itself an agent, which is the precise question OM-001 §17 said it could not answer.

Consequences

• Gain: the commissioning context can reconcile without the person acting as a bus.
• Gain: reports accumulate somewhere durable instead of in a session that will be closed.
• Cost: a return path is a channel, and channels need addressing, ordering, and a story for what happens when delivery fails.
• Cost: writing a real report is work the unit must do at the end, when it is most tempted to stop.
• Trap: mistaking the artifact for the report. A branch is where the work is, not what happened.

Implementation

Put the return address in the commission, so a unit never has to work out where to send anything. Prefer a durable artifact plus a routed notification to either alone: the artifact survives, the notification arrives. Specify what a report must contain (what was done, what was assumed, what was refused, and what the next context needs), because leaving it to each unit's discretion means the reports will not be comparable at the join. And make the missing case loud: a unit that finished without reporting should be visible as such, since silent success and silent failure look identical from outside.

Sample interaction

report · unit 02 · docs-rename
  status     done
  artifact   branch console/docs-rename  (12 files, +340 −295)
  assumed    "shell" in IPC namespaces is load-bearing; left untouched
  refused    did not rename the cargo feature — out of commission scope
  for next   SHELL_ARCHITECTURE.md still names the crate; unit 03 overlaps here
  → routed to: the session that commissioned this unit

Failure signature

The person copies text from one agent into another. Or results that exist, are correct, and were never read by the context that needed them.

Known uses

Exit codes and stdout. Callbacks and reply-to addresses on a message queue. A pull request that closes the issue that commissioned it. Distributed tracing, where a span reports to its parent by construction.

Related patterns

Gather (8), Nested Attribution (7), Plan, Approve, Execute, Receipt (OM-001 · 7).

Reproduced from OM-002 · the canonical entry, which this catalogue does not replace.

The join · Pattern 7

Nested Attribution

Intent

Make every result name who produced it and how far down, so no context ever reports another's work in its own voice.

Motivation

An agent dispatches an agent, which dispatches another. The console rendering this had one progress value per card and nowhere to record a depth, so merging a depth-2 agent's activity into its grandparent's card was available and would have looked fine. It was declined, and the reason is the pattern:

Merging “would put the grandchild's work in the parent's voice.”

The consequence of getting this wrong is not cosmetic. A receipt is the basis for acting on work you did not watch. If it says an agent did something and a different agent did it, every judgement built on that receipt is built on a misattribution, including the judgement of whether to trust that agent with more next time, which is what Progressive Autonomy (OM-001 · 11) runs on.

This is the question OM-001 asked and declined to answer: what a receipt means when the actor was itself an agent. The answer is that a receipt must carry its actor and its depth, and that a surface which cannot show depth must count rather than merge.

Applicability

Any delegation more than one level deep. Also at one level, whenever a result will be summarised by something other than the thing that produced it.

Structure

Participants

Actor is who did it. Depth is how far from the person's own commission. Receipt carries both. Surface shows them, or counts what it cannot show.

Collaborations

Extends Tool-Call Transparency (OM-001 · 8) with the dimension a team adds. It is what makes The Return Path (6)'s reports safe to combine. Without it, Progressive Autonomy (OM-001 · 11) adjusts trust against the wrong agent.

Consequences

• Gain: a receipt you can act on, including acting on the actor.
• Gain: misbehaviour is traceable to a level rather than to a team.
• Cost: another dimension every surface, log line and report must carry.
• Trap: flattening for legibility. The flattened version is easier to read, which is exactly why it gets built.

Implementation

Carry actor and depth on every event from the moment it is emitted; they cannot be reconstructed later. Where a surface holds one value per element, count the levels below instead of folding them in, and say that is what you are doing. Prefer “3 steps, 2 of them by a dispatched agent” to a list of five. When summarising, keep the summariser's identity distinct from the summarised: a parent describing a child's work should read as description, never as a first-person account.

Failure signature

A summary nobody can trace. The question “which agent actually did this?” with no way to answer it. Or a parent's report describing work in a voice that turns out not to be its own.

Known uses

Stack traces. git blame and commit authorship separate from committer. Distributed tracing spans with parent ids. Court records, which never merge a witness's account into the judge's.

Related patterns

The Return Path (6), Tool-Call Transparency (OM-001 · 8), Progressive Autonomy (OM-001 · 11).

Reproduced from OM-002 · the canonical entry, which this catalogue does not replace.

The join · Pattern 8

Gather

Intent

Reconcile N reports into one account, surfacing where they disagree rather than letting the disagreement land in the artifact.

Motivation

Four reports arrive. Read in series, each is internally coherent and each says its unit succeeded. Two of them touched the same file. One proceeded on an assumption that another's work contradicts. Read one after another, the reports hide that contradiction: nothing in any single one is wrong, and the conflict exists only between them.

This is where fan-out either pays off or quietly produces a mess with several confident authors. The failure has a distinctive shape: a merge conflict that is not textual. The files merge cleanly and the system does not work, because two units made compatible edits under incompatible assumptions.

The temptation is concatenation, and it is strong because it looks like the job is being done. Pasting four reports in series is not a gather; it is a pile with a covering note.

Applicability

Every fan-out with more than one unit. The cost scales worse than linearly with team size, because what must be checked is the pairs.

Structure

Participants

Reports arrive with their assumptions declared. Gatherer holds the original decomposition and so knows where units were expected to meet. Account is one narrative. Disagreements are a first-class output, not a footnote.

Collaborations

Consumes The Return Path (6) and is impossible without it. Relies on Nested Attribution (7) so a conflict can be traced to an actor. The assumptions it reconciles are the ones Fire and Forget (4) required units to make and record.

Consequences

• Gain: one account, at the cost of one context's attention, not the person's.
• Gain: semantic conflicts surface before they reach the artifact.
• Cost: real work that cannot be skipped, and it grows with the square of the team.
• Cost: the gatherer needs enough context to judge, which means it cannot be a fresh agent handed four documents.
• Trap: concatenation dressed as synthesis. If the output's length is roughly the sum of the inputs, no gathering happened.

Implementation

Gather in the context that produced the decomposition. It alone knows where units were expected to overlap, which is where to look first. Compare pairwise on the axes conflicts actually travel: the same file, the same claim, contradicting assumptions, and work one unit refused that another assumed was done. Report disagreements explicitly and early; a gather that hides them has made the team less trustworthy than a single agent would have been. And treat “no conflicts found” as a claim requiring evidence, not as the default.

Failure signature

A clean textual merge that produces a system which does not work. Four reports that each say the work is done, and a result that is not. Or a synthesis whose length is the sum of its inputs.

Known uses

Map-reduce's reduce step. Editorial synthesis of several drafts. Code review across parallel branches. Meta-analysis, whose entire discipline is reconciling studies that each concluded something.

Related patterns

The Return Path (6), Nested Attribution (7), Isolation by Construction (3).

Reproduced from OM-002 · the canonical entry, which this catalogue does not replace.

Level one · Composite 1

Plain Fan-Out

Intent

Split work into units that never meet, run them at once, and reconcile their reports: the default arrangement, named so that the others read as departures from something rather than as inventions.

Motivation

This is the arrangement OM-002 describes end to end, and it is the right one often enough that it gets chosen by default rather than on purpose. Naming it costs nothing and buys the ability to say “this is not a fan-out” about the other five.

Its own failure is specific and common: work that does not partition, dispatched as though it does. Units then discover they need each other's results, proceed on guesses about them, and hand the whole problem to the gather, which is where the cost lands, all at once, in the one step that cannot be parallelised.

Applicability

When the units are genuinely independent: different files, different questions, different subsystems. When the number of units is known before starting. When each unit's result is useful on its own, so a failed unit costs one unit instead of the run.

Structure

What it changes

An empty table would have disqualified any other candidate. This one is admitted as the baseline against which the tables below are read, and it is the only entry in this document with that exemption.

Participants

Commission is split before anything runs. Units are peers and do not communicate. Gather holds the decomposition and so knows where the units were expected to touch.

Collaborations

All eight of OM-002, in the order that document sets out: Proposed Dispatch (1), Authority at Dispatch (2) and Isolation by Construction (3) at the split; Fire and Forget (4) and Status Board (5) in flight; The Return Path (6), Nested Attribution (7) and Gather (8) at the join.

Consequences

• Gain: wall-clock time is the slowest unit, not the sum, which is the whole reason to do any of this.
• Gain: a failed unit costs one unit.
• Cost: the gather is serialised and its work grows with the pairs, not with the units.
• Trap: partitioning work that does not partition. The units succeed, and the incoherence is discovered at the join by the one step with no slack.

Implementation

Decide the partition before dispatching and write down where units are expected to meet: that list is the gather's first search. Prefer units whose results are useful alone. When two units keep needing each other's output, that is not a coordination problem to solve with more messages; it is the wrong arrangement, and Composite 2 is the right one.

Failure signature

The same file in three units' reports. Or units that each proceeded on a guess about what another one did, producing a clean textual merge and a system that does not work: Gather's signature, arriving because the arrangement was wrong rather than because the gather was.

Evidence

Inherited measurements and practice. This is OM-002's arrangement, and its evidence is OM-002's.

Known uses

Map-reduce's map phase. make -j. A CI matrix. Any batch of independent jobs against a pool of runners.

Related patterns

Pipeline (Composite 2), Scout then Swarm (Composite 3), Gather (OM-002 · 8).

Reproduced from OM-003 · the canonical entry, which this catalogue does not replace.

Level one · Composite 2

Pipeline

Intent

Run units in series, each one's report standing as the next one's commission, when the work does not partition but does decompose into stages.

Motivation

Some work has parts and no partition. Design, then implement, then test, then document. Survey, then rewrite. Each stage needs what the one before it produced, so dispatching them at once produces three units guessing at each other's output and a gather that has to invent the missing order after the fact.

The arrangement is old and the interesting part is what happens at the seam. The Return Path and the next Authority at Dispatch are the same object. That is not a convenience; it changes what a report is for. In a fan-out a report is an account for a human or a gatherer to read. Here it is an input to a machine that will act on it without discussion, which means an under-specified report does not produce a question; it produces a wrong stage.

The second change is quieter and is the reason this arrangement fails in ways fan-out does not. In a fan-out, units make assumptions independently, and the join is where incompatible ones collide and get caught. In a pipeline nothing collides. An assumption made in stage one is inherited by stage four unexamined, because there is no second opinion anywhere in the line. Errors do not conflict here; they compound.

Applicability

When each stage genuinely needs the previous stage's output. When the intermediate artifacts are durable and inspectable. Not applicable when stages are only conventionally ordered: “design then build” is a real dependency; “front end then back end” often is not, and pipelining it buys nothing but latency.

Structure

What it changes

Participants

Stages run one at a time, in a fixed order. Seam is a report that is also a commission. Artifact at each seam is durable, so any stage can be re-run without repeating its predecessors.

Collaborations

Depends absolutely on The Return Path (OM-002 · 6), which stops being a convenience and becomes the mechanism. Leans on Assume or Ask (OM-001 · 5) at every stage, since a stage that stops to ask stalls the line instead of one unit. Nested Attribution (OM-002 · 7) is what lets a defect at stage four be traced to the stage that introduced it.

Consequences

• Gain: work that cannot be partitioned is still delegable, one stage at a time.
• Gain: each seam is an inspection point where a person can intervene cheaply, before the next stage acts.
• Cost: no parallelism. Wall-clock is the sum, and the arrangement buys unattendedness, not speed.
• Cost: a defect at stage one is paid for by every stage after it.
• Trap: an under-specified report. In a fan-out it produces a vague account; here it silently produces a wrong stage, and the wrongness is inherited.

Implementation

Fix the report's shape before the first dispatch and make every stage emit it: the seam is a contract, and a contract nobody wrote is discovered by breaking it. Keep every intermediate artifact durable and addressable, so re-running stage n does not mean re-running stage one. Carry assumptions forward explicitly in the report instead of in the work, since they are the one thing this arrangement will never catch on its own. Where a stage's assumption is load-bearing, the cheap remedy is to hang an Adversarial Verify (Composite 6) on that seam alone instead of abandoning the pipeline.

Sample interaction

seam · stage 1 → stage 2
  artifact   branch survey/console-naming  (notes.md, 1 file)
  assumed    "shell" in IPC namespaces is load-bearing
  refused    did not touch the cargo feature name
  commission stage 2 acts on notes.md only; may not widen scope
  → dispatched as unit 02 with this report as its commission

Failure signature

A person pasting one unit's output into the next unit's prompt: The Return Path's signature in series rather than in parallel. Or a defect at the last stage traced back three stages, each of which was correct given what it was handed. Or an early stage re-run because its output was not kept.

Evidence

Practice and adjacent prior art. The compounding-assumption claim is reasoning about topology and has no incident on record: slot 1.

Known uses

Unix pipes. Build DAGs. Compiler passes. Editorial workflows where a draft is commissioned, edited and then fact-checked by different hands.

Related patterns

Plain Fan-Out (Composite 1), Scout then Swarm (Composite 3), The Return Path (OM-002 · 6).

Reproduced from OM-003 · the canonical entry, which this catalogue does not replace.

Level one · Composite 3

Scout then Swarm

Intent

Spend one read-only unit on a survey whose product is the decomposition, then fan out over it: for work nobody present knows the shape of.

Motivation

Proposed Dispatch (OM-002 · 1) assumes a primary agent that already holds the context, and it is right whenever one exists. Often none does. The work is in a part of the system nobody has touched this month, and the person and the primary agent are equally ignorant of it.

Fanning out anyway has a specific and invisible cost: every unit spends its first minutes doing the same orientation. Five units read the same five files, form the same picture, and each writes a paragraph describing it. Nothing errors. The cost is paid five times and shows up as “agents are slow” rather than as duplicated work.

The remedy is a stage, not a pattern: one unit whose commission is to look and report, with no authority to change anything, followed by a fan-out whose partition is the scout's own map.

The map earns its keep twice. It is the decomposition, and it is also the expectation, so the gather at the end has something to check the results against, which a fan-out that partitioned by guesswork does not.

Applicability

When the shape of the work is unknown to everyone present. When the cost of a bad partition is high: overlapping units, or a gap nobody notices. Not applicable when the primary agent genuinely holds the ground: then the scout is a stage that costs latency and returns what was already known.

Structure

What it changes

Participants

Scout reads and reports, and may not write. Map is a list of separable jobs, not prose. Swarm is a plain fan-out over that list. Gather holds the map as its expectation.

Collaborations

Composes Pipeline (Composite 2) and Plain Fan-Out (Composite 1), which is the first evidence in this document that composites nest. Realises Proposed Dispatch (OM-002 · 1) where no primary agent can. Its map is Constrained Choice (OM-001 · 6) made into a work list.

Consequences

• Gain: orientation is paid once instead of N times.
• Gain: the partition is made by something that looked, and the gather inherits an expectation.
• Gain: the scout is safe to dispatch before anything is decided, because it cannot change anything.
• Cost: one unit of latency before any work starts.
• Trap: a scout that returns prose. A map that cannot be split is a briefing, and somebody must now do the decomposition by hand from it.
• Trap: trusting the map after the ground moves. It is a snapshot, and a swarm dispatched hours later may be partitioning a tree that has changed.

Implementation

Commission the scout for a list, and say so in the commission: N jobs, each with the files it touches and what it must not touch. Give it read-only scope and nothing else, so it can be dispatched without a decision. Have the person approve the map instead of the units: that is the moment judgement is worth most, and it is one decision instead of N. Carry the map into the gather verbatim; a gather that only sees reports cannot notice a job nobody did.

Failure signature

Five reports containing the same paragraph about the same files. Or a fan-out where two units renamed the same thing differently because neither knew the other existed. Or a scout's output that a person has to turn into units by hand, which means the scout did half the job and handed back the half that does not scale.

Evidence

Practice and reasoning about topology. The duplicated-orientation cost has not been measured: slot 2.

Known uses

A survey before a refactor. git grep before splitting the work. Reconnaissance in the sense the word is borrowed from. A planning step whose deliverable is a list of issues rather than a document.

Related patterns

Plain Fan-Out (Composite 1), Pipeline (Composite 2), Proposed Dispatch (OM-002 · 1).

Reproduced from OM-003 · the canonical entry, which this catalogue does not replace.

Level one · Composite 4

Loop Until Dry

Intent

Repeat rounds of fan-out, deduplicating against everything seen so far, until some number of consecutive rounds return nothing new: for work whose size is not known before starting.

Motivation

Some work has no denominator. Find the bugs. Find every place this term is used incorrectly. Find the cases this parser mishandles. There is no list to partition because the list is what you are producing, and any fixed number of units is a guess about a quantity nobody has measured.

The guess is usually made once and never examined. Ten agents are dispatched because ten felt right; they return thirty findings; the run is declared complete. Whether there were thirty-one is unknown and unknowable from inside the run, and the tail (which is where the interesting findings live, because the obvious ones were found by everybody) is systematically missed.

Convergence has to be defined by the results instead. Run a round, deduplicate against everything seen in every previous round, and stop when consecutive rounds add nothing. The stopping condition is a property of the output, not a parameter.

The trap is precise and worth stating early because it is easy to build and hard to notice: deduplicate against everything seen, not against everything accepted. If findings that were examined and rejected are not in the seen-set, they will be rediscovered every round, every round will look productive, and the loop will never dry.

Applicability

Whenever the number of things to find is unknown: bug hunts, audits, sweeps for a pattern across a codebase, edge-case discovery. Not applicable where the work is enumerable: if the list can be computed, computing it is cheaper and complete.

Structure

What it changes

Participants

Round is a fan-out. Seen-set holds every finding ever surfaced, accepted or rejected. Stopping rule is stated before the first round. Budget is the other stopping rule, and the honest one.

Collaborations

Contains Plain Fan-Out (Composite 1) as its round, and usually Adversarial Verify (Composite 6) as its filter: findings must be judged before they enter the kept set, though they enter the seen-set either way. Honest Gauge (OM-001 · 12) governs how “dry” is reported: two empty rounds is a stopping rule, not a proof of completeness, and a surface that says “all findings” has lied.

Consequences

• Gain: coverage is bounded by results rather than by a number somebody guessed.
• Gain: the tail gets found, which is where the findings nobody else has live.
• Cost: unbounded in principle. Without a budget, a loop that never dries never stops.
• Cost: rounds after the first are increasingly expensive per finding, and the last productive round may cost more than everything before it.
• Trap: deduplicating against the accepted set. Rejected findings return every round, every round looks productive, and the loop cannot converge.
• Trap: calling one empty round dry. Variance between rounds is large, and a single empty round is well within it.

Implementation

State the stopping rule before the first round (K consecutive empty rounds), and state a budget alongside it, because the rule alone does not terminate. Key the seen-set on something stable enough to match near-duplicates: the same finding described in two ways is the common case, and an exact-string key will never dedupe it. Tell each round what is already known, or it will spend its budget rediscovering it. And report the rule with the result: “two consecutive rounds returned nothing new” is a true sentence, and “we found everything” is not one this arrangement can support.

Sample interaction

sweep · incorrect uses of "shell" in prose
  rule    stop after 2 consecutive rounds with nothing new
  budget  8 rounds
  round 1  5 units   +7 new   (7 seen)
  round 2  5 units   +2 new   (9 seen, 3 rejected — still seen)
  round 3  5 units   +0       dry 1/2
  round 4  5 units   +0       dry 2/2 → stop, 6 kept

Failure signature

A team size chosen because it felt right, and a report that says “we found N” with no account of what would have found N+1. Or the same three findings surfacing in every round, with the loop apparently productive and never converging. Or a run declared complete after one quiet round.

Evidence

Practice and adjacent prior art. The claim that a fixed count systematically misses the tail is reasoning, and the run that would demonstrate it is slot 3.

Known uses

Fuzzing to coverage saturation. Capture–recapture sampling in ecology, whose entire purpose is estimating what has not been seen. Bug bashes run until the finding rate falls. Search that stops when a page of results adds nothing.

Related patterns

Plain Fan-Out (Composite 1), Adversarial Verify (Composite 6), Gather (OM-002 · 8).

Reproduced from OM-003 · the canonical entry, which this catalogue does not replace.

Level one · Composite 5

Panel

Intent

Give several units the same question, kept apart on purpose, and make the disagreement between their answers the product rather than a problem.

Motivation

Every arrangement so far divides work. A panel duplicates it (the same question to each unit, no partition at all), and that inversion changes what the join is for.

In a fan-out, disagreement between reports is a warning: two units have contradicted each other and something must be reconciled before it reaches the artifact. In a panel, agreement is the uninformative outcome and disagreement is the finding. Where three independent answers diverge, you have learned that the question is underdetermined, which is worth more than any one of the answers.

That only holds if the units are genuinely independent. Let them see each other's drafts and they converge: not because the question was settled but because the channel carried an answer. Unanimity produced by a shared channel is indistinguishable from unanimity produced by a clear answer, and only one of them is worth anything. This is why isolation, which in a fan-out is about files, is here about judgement.

The other honest limit: a panel is for questions no test can settle. Convening three units to decide whether a function returns the right value is money spent to reproduce something a test would have told you for free.

Applicability

Questions of design, approach, naming, risk, or interpretation, where there is no oracle and being wrong is expensive. Where the units can be kept independent. Not applicable to anything checkable, and not applicable where the disagreement will be averaged, since averaging discards exactly what the arrangement was bought for.

Structure

What it changes

Participants

Question is identical for every unit, and its wording is now a shared dependency. Members are isolated from each other for the duration. Adjudicator applies a rule fixed before the answers arrived. Disagreements are an output in their own right.

Collaborations

Inverts Plain Fan-Out (Composite 1): same work to every unit rather than different work to each. Distinct from Adversarial Verify (Composite 6), which is asymmetric: a panel answers a question, a verifier attacks an answer. Depends on Nested Attribution (OM-002 · 7) to keep the members' voices separate.

Consequences

• Gain: an underdetermined question is revealed as one, before a decision is built on it.
• Gain: the range of reasonable answers becomes visible, which no single answer shows.
• Cost: N times the work for one question, with no division of labour at all.
• Cost: someone must adjudicate, and adjudication is harder than reconciliation.
• Trap: leaked context. One member seeing another's answer produces unanimity that reads as strong evidence and is an artifact of the channel.
• Trap: convening a panel on a checkable question, which buys an expensive opinion about a fact.

Implementation

Give every member the same question, verbatim, and vary nothing but the seat: a panel whose members were asked slightly different questions cannot disagree meaningfully. Keep them from each other for the duration, including from each other's artifacts; the leak is usually a shared workspace or a helpful summary, not a message. Fix the adjudication rule before the answers arrive, because a rule chosen afterwards is a preference with a quorum. Report the disagreement in the output, not only the verdict. And if a test could answer the question, run the test.

Sample interaction

panel · should the crate keep the name "shell"?
  rule     3 members, independent; verdict needs 2; dissent always reported
  member 1 rename — the word collides with the OS sense
  member 2 rename — but keep the IPC namespace, it is load-bearing
  member 3 keep — the collision is theoretical, the churn is not
  verdict  rename (2 of 3)
  dissent  member 3 names a cost the others did not price

Failure signature

Unanimity you cannot account for. Or a panel report that reads as one voice, so no reader can tell whether three units agreed or one summarised. Or a decision made by panel that a five-line test would have settled.

Evidence

Practice and adjacent prior art: juries and review panels have worked out the independence rules over centuries. The claims here about what leaked context does are reasoning; slot 4 is what would settle them.

Known uses

Juries, and their rules against discussing the case outside the room. Blind peer review. Ensemble methods, where the diversity of the members is the source of the gain. Design reviews with independent written positions collected before discussion.

Related patterns

Adversarial Verify (Composite 6), Plain Fan-Out (Composite 1), Isolation by Construction (OM-002 · 3).

Reproduced from OM-003 · the canonical entry, which this catalogue does not replace.

Level one · Composite 6

Adversarial Verify

Intent

Commission units to refute a result rather than to review it, with the burden of proof on the claim and a rule fixed before the verdicts arrive.

Motivation

A unit finishes and reports success. The report is coherent, the reasoning is legible, and it is wrong. Nothing in the fan-out will catch this: the gather compares reports against each other, and a single confident report has nothing to contradict it.

The obvious remedy, asking another unit to check it, fails in a specific way. Handed the claim and the reasoning, a checker reads the reasoning, finds it plausible, and agrees. It has been given the conclusion and a path to it, and confirming is the cheapest thing it can do. What comes back is a confirmation whose information content is close to zero, and which now reads as independent corroboration.

Two changes fix it, and both are asymmetries. The verifier's commission is to refute, not to check: the default outcome is that the claim fails, and surviving is the exception. And what it is given is the claim and the evidence, not the producer's reasoning, because reasoning is contagious, and a verifier that inherits it is not a second opinion but an echo.

This is where Isolation by Construction (OM-002 · 3) stops being about files. What must be kept apart is not two writers but two judgements, and the boundary is informational, not physical.

Applicability

When a claim is expensive to be wrong about and cannot be checked mechanically. When a run's findings will be acted on without further review. Not applicable when a test exists, and not applicable to everything indiscriminately: verification costs as much as production, and verifying every result doubles the run.

Structure

What it changes

Participants

Producer emits a claim and the evidence for it. Refuters receive both, and not the rationale. Rule is fixed in advance and stated. Verdict defaults to refuted where a refuter is uncertain, because the burden sits on the claim.

Collaborations

Usually the filter stage inside Loop Until Dry (Composite 4), and a good repair for a load-bearing seam in a Pipeline (Composite 2). Distinct from Panel (Composite 5) by asymmetry: a panel has no incumbent answer, and here the answer is the thing under attack. Sharpens Progressive Autonomy (OM-001 · 11), since a producer whose claims survive refutation has earned something measurable.

Consequences

• Gain: confident wrong results are caught by something with an incentive to catch them.
• Gain: what survives is worth more, and the survival rate is itself a signal about the producer.
• Cost: doubles or triples the cost of every claim it is applied to, which is why it is applied selectively.
• Cost: false refutations. A refuter commissioned to break things will sometimes break a correct claim, and somebody must adjudicate that.
• Trap: handing over the reasoning “for context”. It is the single change that turns this arrangement back into an expensive way to agree.
• Trap: a rule chosen after the verdicts. Deciding that one refutation is enough, once you have seen which claim it kills, is not a rule.

Implementation

Word the commission as refutation: “find the input on which this is wrong”, not “review this”. Send the claim and the evidence; withhold the rationale, and check what the commission carries rather than what it was meant to. Default an uncertain refuter to refuted, since the point is to make survival mean something. Fix the rule and the number of refuters before dispatch. And prefer several verifiers with different angles (correctness, cost, does it reproduce) to several identical ones, because redundancy catches only what one lens can see.

Failure signature

Everything verifies. A confirmation rate near one is not evidence that the work is good; it is evidence that the verification is not working, and it is the cheapest thing in this document to measure. Or verifiers whose reports restate the claim approvingly. Or a verdict rule that changed once the verdicts were in.

Evidence

Reasoning about topology and adjacent prior art. The confirmation-rate comparison that would settle it is slot 5, the one open slot here that could be closed in an afternoon.

Known uses

Red teams. Adversarial review in security. Falsification in experimental design, where a hypothesis earns standing by surviving attempts to kill it. A defence that never sees the prosecution's reasoning, only its evidence.

Related patterns

Panel (Composite 5), Loop Until Dry (Composite 4), Isolation by Construction (OM-002 · 3).

Reproduced from OM-003 · the canonical entry, which this catalogue does not replace.

Level two · Pattern 1

Ordered by Readiness

Intent

Order the surface across teams by what needs a person, not by what is happening, so the scarce resource is spent on decisions rather than on scanning.

Motivation

Status Board (OM-002 · 5) answers what is happening, and at team scale that is the right question: the person wants to know whether to intervene. Across teams it is the wrong one. Four teams are always happening. The question is which of them needs the person next, and for what decision.

The distinction that makes this a separate pattern rather than the same surface scaled up: readiness is not status. A team that is done is not necessarily ready to land, and a team that is running may have been blocked on a thirty-second answer for six hours. A surface ordered by status buries the second behind three teams that are working fine, and the loss is invisible because nothing failed.

The states that matter at this level are about the person, not the work: blocked on you, ready to land, running, finished and waiting, rotting. Only the first demands attention now; the second demands a decision soon; the rest demand nothing, and a surface that presents all five with equal weight has made the person do the sorting.

Applicability

Whenever more than about two teams run at once. Especially where teams are long-lived and the person's attention is the constraint, which at this level it always is.

Structure

Participants

Teams report their own readiness, which they know and the surface does not. Readiness orders by the decision being asked for. Person works down the list and stops when nothing is asking.

Collaborations

Sits above Status Board (OM-002 · 5) and inverts its sort key. Depends on Honest Gauge (OM-001 · 12): “blocked on you” must be wrong only when the system is wrong, or the list stops being read. Ambient Activity Channel (OM-001 · 9) is how the one state that matters (a team newly blocked) reaches a person who is deliberately looking elsewhere.

Consequences

• Gain: the person's scarce resource is spent on decisions instead of on finding which decision to make.
• Gain: a blocked team's waiting time becomes visible, which is the largest silent loss at this level.
• Cost: teams must classify their own readiness, and a team that overstates it teaches the person to distrust the list.
• Trap: a notification per team. Interrupting on every state change reproduces across teams exactly what Fire and Forget (OM-002 · 4) solved at team scale, and the person must be able to not look.
• Trap: sorting by urgency rather than by readiness. Urgency is a claim about the world; readiness is a claim about the work, and only one of them is knowable by a team.

Implementation

Sort by the decision being asked for, and show the age of that decision: a team blocked six hours reads differently from one blocked six minutes, and the age is the number that changes behaviour. Distinguish done from ready to land; they are different states and conflating them is how finished work sits unlanded. Let the list be empty, and make an empty list mean something: nothing here needs you. Keep the team-level surface underneath instead of replacing it, since once a team is chosen the question reverts to what is happening.

Sample interaction

4 squads
  presence   blocked on you   6h12m   "rename the capability or keep it?"
  patterns   ready to land            2 files, no conflicts with console
  console    running                  3 units, last event 40s ago
  voice      running                  1 unit, quiet 22m — no news, not no progress

Failure signature

A team that sat blocked on a small decision while the person watched one that was fine. Or the person opening each team in turn to find out which one needs them: Status Board's signature one level up, with the difference that here a status surface is what produces it rather than what cures it.

Evidence

Practice, and reasoning from the asymmetry in §12. The waiting time that would make the loss concrete has not been measured: slot 6.

Known uses

A code review queue sorted by “waiting on you”. Air traffic control strips, which are ordered by what needs a decision next. Kanban boards where the blocked column is read first. Triage in any sense of the word.

Related patterns

Landing Order (OM-003 · 3), Status Board (OM-002 · 5), Honest Gauge (OM-001 · 12).

Reproduced from OM-003 · the canonical entry, which this catalogue does not replace.

Level two · Pattern 2

Re-entry Note

Intent

Have each team maintain a short note written for the person's return, so that coming back to it costs reading rather than reconstruction.

Motivation

The cost of running several teams is not the running. It is the switch. Returning to a team after a day away, the person has to rebuild: what this area is for, what was decided and why, what it is waiting on, what will break if it lands after the other one. None of that is written down anywhere in that form. The transcript is a record of how the state was reached, which is the expensive way to learn what it is. The diff says what changed, not what was intended.

So the person reconstructs, and the reconstruction is the real cost of running several at once: paid on every switch, invisible because it looks like working, and rising with the number of teams.

This is Durable Memory (OM-001 · 14) with the memory belonging to the wrong party. There, an agent keeps what matters so the person need not restate it. Here the reader is the person, and what must survive is the state of an area they were absent from, which means the note has to be written by the team, for a reader who was not there, and maintained, not composed once.

The obvious objection is right and is the pattern's main cost: a second artifact can go stale, and a stale note is worse than no note, because it will be believed. That makes this an application of Honest Gauge (OM-001 · 12) as much as of memory: a note that is not maintained must be visibly not maintained.

Applicability

Whenever the gap between visits to a team is long enough that state must be rebuilt: in practice, more than a few hours. Not applicable to a team being worked continuously; there the note is overhead and the working context is the memory.

Structure

Participants

Gatherer writes the note, because it already holds the decomposition and has just read every report. Note has a fixed shape and is short enough to read in full. Person reads it on return and is not expected to read anything else first.

Collaborations

An application of Durable Memory (OM-001 · 14) where the reader is the person. Written at the end of Gather (OM-002 · 8), which is the only moment the whole state is in one place. Feeds Ordered by Readiness (OM-003 · 1), whose one-line summary of a team is the note's first field. Governed by Honest Gauge (OM-001 · 12), because a stale note is a green light over a broken system.

Consequences

• Gain: switching teams costs reading instead of rebuilding, which is what makes four to six of them possible at all.
• Gain: decisions survive with their reasons attached, so they are not re-litigated on every return.
• Cost: a second artifact to maintain, and the maintenance falls at the end of a gather when everything wants to stop.
• Trap: a note that becomes a summary of the transcript. Then it grows without bound, stops being readable in full, and the person goes back to the diff.
• Trap: staleness that does not show. A note with no date is a claim about the present made at an unknown time.

Implementation

Fix the shape and keep it short: what this team is for, where it stands, what it is blocked on, what has been decided and when, and what must land before it. Write it at the end of every gather, as part of the gather instead of as a chore after it. Date every line that is a decision, since the ones without dates are the ones that will mislead. Keep it in the team's own workspace so it travels with the work. And prefer replacing lines to appending them: a note that only grows is a transcript with extra steps.

Sample interaction

re-entry · presence
  for        the ambient light channel and its states
  state      2 units done, 1 blocked
  blocked    "capability" vs "affordance" in the public API — needs you
  decided    13 Aug · states are named, not numbered (breaks the old client)
  lands after console/docs-rename, which renames the same symbols

Failure signature

Reading a diff to remember why a team exists. Typing “where were we?” to an agent. The same context explained twice in a week to the same team. Or a decision re-made differently, because the first one was in a transcript nobody reopened.

Evidence

Practice. The comparison that would give the claim a number (reconstruction timed against reading) is slot 7.

Known uses

Handover notes at a shift change, in every trade that has shifts. A ship's log. The STATUS file at the top of a long-running branch. A good issue description, maintained, not written once.

Related patterns

Ordered by Readiness (OM-003 · 1), Durable Memory (OM-001 · 14), Gather (OM-002 · 8).

Reproduced from OM-003 · the canonical entry, which this catalogue does not replace.

Level two · Pattern 3

Landing Order

Intent

Decide the order in which finished work lands, explicitly and before it is finished, because the shared trunk is the one thing isolation cannot copy.

Motivation

Isolation by Construction (OM-002 · 3) makes parallel work possible by giving every unit its own copy, and it says plainly that conflict is deferred rather than removed: deferred to the join, where a person can see it. At this level, every team's join arrives at the same place: one repository, one CI, one main branch, one release, one production database. Isolation copies workspaces. It cannot copy the trunk.

Three things follow, and none of them is a team-level problem.

Finished work rots while it waits. A branch that is correct on Tuesday is a rebase on Thursday, because the ground moved under it. The cost of landing rises with the time held, so holding finished work for a coherent release is not free; it is a loan against a rising rate.

A landing changes other teams' ground. Team B's finished work can be invalidated by team A landing first, and nobody is informed, because A's units know only A's work. The failure surfaces as a CI break in a branch that nobody touched.

And the order is a decision no unit can make. Each team knows its own readiness and nothing about the others; the ordering information exists only in the person, which is precisely the party with no capacity to spare. Uneven readiness guarantees the queue is never empty.

Applicability

Whenever two or more teams land into the same target. The pattern is worth its cost from the second team onwards, and by four it is the dominant constraint at this level.

Structure

Participants

Teams produce finished work at different times. Trunk is the one target, and the list of things like it (CI capacity, the release, the production database, a token with one permitted caller) is the set of singletons shared across teams. Order is stated at commission time and revised out loud. Person owns it, because nothing else can.

Collaborations

Receives what Isolation by Construction (OM-002 · 3) defers, at the level where the deferral finally has to be paid. Depends on Ordered by Readiness (OM-003 · 1) to distinguish done from ready to land. A change of order is a dispatch to the teams whose ground moved, not a note. That dispatch is a Authority at Dispatch (OM-002 · 2) like any other.

Consequences

• Gain: invalidation is anticipated, not discovered, and by the party that can act on it.
• Gain: the rot cost becomes visible as a queue instead of as a series of unexplained rebases.
• Cost: an order decided early is decided with less information than one decided late.
• Cost: landing small and often costs more landings, each with its own ceremony.
• Trap: holding finished work for a coherent release. The coherence is real and the interest is compounding, and the trade is usually made by default, not on purpose.
• Trap: treating the order as a private plan. If it lives only in the person's head, the teams cannot warn you when it is wrong.

Implementation

State the intended order when the teams are commissioned: it is part of the decomposition, not an afterthought, and it is cheapest to get right before anything is built. Keep a written list of the shared singletons: the trunk, CI capacity, the release channel, the production database, the domain, any token with one permitted caller, and the person. Those are what cannot be isolated, and everything that contends is contending for one of them. Prefer landing small and often, and treat a long-held branch as a cost that is accruing, not as work that is safe. When the order changes, dispatch that fact to the teams it moves, and expect them to re-verify, not assume.

Sample interaction

landing queue · 13 Aug
  1  patterns/name-states     ready      no shared symbols
  2  console/docs-rename      ready      renames what presence depends on
  3  presence/capability-api  blocked    re-verify after 2 lands
  —  voice/streaming-fix      running    lands last, touches the trunk widely
  note: 2 before 3 was decided at commission time, not at merge time

Failure signature

Two finished branches waiting on each other while a person decides from memory which goes first. Or a team's work invalidated by another's landing, discovered by CI on a branch nobody touched. Or a rebase that costs more than the work it is rebasing.

Evidence

Practice, and reasoning from the singleton list. The invalidation incident that would make the cost concrete is slot 8.

Known uses

Merge queues and landing trains. Release trains with a fixed cadence. Work-in-progress limits in kanban, which exist because finished-and-unlanded work is the expensive kind. A slipway, which admits one hull at a time regardless of how many are built.

Related patterns

Ordered by Readiness (OM-003 · 1), Isolation by Construction (OM-002 · 3), Gather (OM-002 · 8).

Reproduced from OM-003 · the canonical entry, which this catalogue does not replace.

Ambient Signals · Pattern 1

Standing Assertion

Intent

Re-send a resting state on a timer rather than on change, because an ambient channel has no history and no acknowledgement, and both of its failure modes are silent.

Motivation

A live cue repaints every frame, so a lost packet self-corrects in 66 ms and nobody notices. A resting state is sent once. If that single datagram is lost, or arrives before the device is ready, or the consumer restarts afterwards, the state is wrong forever, and the producer believes it succeeded, because as far as it knows nothing failed.

Both failures happened, one layer apart, within a single session. A lamp restores its own default on power-cycle; the renderer's colour frame went out microseconds later in the same tick; the emit path sent only on change. The lamp sat white while every log line said violet. Diagnosing it required querying the device directly, which itself only works with the renderer stopped, because the renderer holds the fixed reply port. Fixing it exposed the identical bug one level up: the tray also announced presence only on change, so a renderer started after the tray never learned there was anyone to be present.

Applicability

Any state that is long-lived, ambient, and sent over a transport without acknowledgement, to a consumer that can restart independently of the producer.

Structure

Participants

The producer, which holds the state and can restart. The transport, unacknowledged and unordered. The consumer, which renders and can restart independently. The device, which has its own power state and its own defaults and can revert underneath both of them.

Collaborations

The producer re-asserts on a period by clearing its own last-sent cache instead of tracking what the consumer knows: the consumer's knowledge is exactly what is not observable. Live cues are exempt: they repaint anyway, and re-asserting them would double the traffic to fix a problem they do not have.

Consequences

Gain: both silent failures become self-healing within one period, including the one nobody anticipated (a consumer that starts later than the producer). Cost: traffic proportional to time, not to events, and a period that is a guess. Trap: it reads as belt-and-braces until you have watched a resting state be wrong for an hour while the producer reported success, and then it reads as the minimum.

Implementation

Here the renderer re-asserts colour and brightness every 3 s and the tray heartbeats presence every 5 s. Two producers, two periods, because they are separate processes with separate restart behaviour and a shared constant would only imply a coupling that does not exist.

Failure signature

A resting state that is confidently wrong, with a clean log. The person has no reason to doubt what they see, and the only way to find it is to ask the device, which, on this hardware, first requires stopping the thing that is lying about it.

How you would know this is unnecessary

If the transport were reliable and ordered and a consumer could ask for current state on connect. Either alone is insufficient, and that is the useful part: a renderer that issued what is the present state? at startup would not need the heartbeat, and a protocol with acknowledgements would not need the re-assert timer. The rule is a consequence of fire-and-forget datagrams to a device that can power-cycle underneath you, plus consumers that restart independently. Remove any one of those three and check again.

Related patterns

Corrects Ambient Activity Channel (OM-001, 9), whose implementation note says a time-to-live is sufficient: it is sufficient for a live cue and does nothing for a resting state. Governed by Honest Gauge (OM-001, 12). Enables Verified Presence (2), which has nothing to assert with until a resting state can be trusted to arrive.

Reproduced from OM-004 · the canonical entry, which this catalogue does not replace.

Ambient Signals · Pattern 2

Verified Presence

Intent

An indicator asserts only what it has checked, because adding a confident signal makes you responsible for everything it appears to claim, including things nobody was measuring before you added it.

Motivation

The resting glow originally meant Agent mode is selected. It read as she can hear you. Those two diverge the moment the channel dies (service restarted, port lost, session gone), and a dead agent looked identical to a live one until you had spoken an entire sentence into nothing.

While the surface was silent about reachability, this was a gap. The moment the lamp began asserting a confident resting glow, the same gap became a lie. The indicator did not create the blindness. It made it load-bearing, and that is the general lesson: a new signal inherits responsibility for everything it appears to assert, including conditions that were previously nobody's job because nothing depended on them.

Applicability

Whenever a signal is added to a surface a person will trust without reading, which is every peripheral channel, by definition, since not being read is what peripheral means.

Structure

Three things that are easy to conflate, and the pattern is the insistence that they are three: what the system intends (a mode, a setting, a configuration), what the system has verified (a probe that completed), and what the indicator says. The indicator is wired to the second, never the first. The probe runs on its own schedule and its own thread, and its result, not the intention behind it, is what reaches the channel.

Participants

The indicator, which must not assert ahead of evidence. The prober, on a thread of its own. The subject, which may be unreachable in ways that hang, not refuse. The person, who reads the indicator without deciding to.

Collaborations

The probe result is published through Standing Assertion rather than emitted once on change, so a consumer that restarts learns the current answer rather than the last transition. A flip in reachability re-announces immediately rather than waiting for the next heartbeat, because the whole value is in the flip.

Consequences

Gain: the question you have before pressing a key gets an answer, from across the room. Cost: a probe, a cadence, and a new set of failure modes belonging to the probe itself. Trap: the probe must not run on the thread that draws the interface. The health check has a 2 s timeout and the surface's loop is the message pump; probing inline freezes the icon and the overlay for two seconds every time the channel accepts a connection and then hangs, which is the exact condition being probed for.

Implementation

Probe every 10 s, on a dedicated thread, unconditionally. That last word is load-bearing and was nearly lost: the probe originally ran only while a particular mode was selected, and when modes were deleted it would never have run again, leaving the lamp asserting something nothing was checking. A conditional probe behind a condition that later disappears is worse than no probe, because the indicator does not go with it.

Failure signature

The person speaks a complete utterance into a channel that is not there, and learns only when they stop. The cost of the discovery is one whole interaction, every time, and it is paid before any feedback exists, which is why an ambient answer is worth a thread of its own.

How you would know this is unnecessary

If failure were immediate and visible at the moment of acting. This indicator exists because push-to-talk gives no feedback until after you have spoken. On a surface where the attempt itself reports failure synchronously (a button that greys out, a send that errors), an ambient reachability signal is redundant, and adding one would only create a second thing that can be wrong.

Related patterns

Obeys Honest Gauge (OM-001, 12), of which this is the peripheral case and the harder one: a gauge that lies is worse when it is trusted without being read. Specialises Ambient Activity Channel (OM-001, 9). Needs Standing Assertion (1). Ranked by One Ordering, One Place (5).

Reproduced from OM-004 · the canonical entry, which this catalogue does not replace.

Ambient Signals · Pattern 3

Closed Vocabulary

Intent

Let the agent name a state from a fixed list and let the renderer own what that looks like, so unsafe output is not rejected but inexpressible.

Motivation

An agent that can ask a light for a colour, a brightness and a waveform can ask it to strobe. The obvious defence is a validator, and a validator is a check somebody has to remember to write, can be bypassed by a second code path, and drifts the moment it is duplicated.

A vocabulary with no field for a waveform cannot carry one. So never allow agent-generated strobing stops being a rule anyone enforces and becomes a fact about what is sayable. The agent asks for focus or evening; pigment, ramp and dynamics never leave the renderer.

This is Ambient Activity Channel's the channel reports state, never instructions promoted from a design note to the thing that makes the layer safe to leave unsupervised.

Applicability

Whenever an unsupervised agent drives an actuator in a shared physical space, and the harmful states are a describable class.

Structure

Participants

The agent, which may name but never specify. The relay, which forwards and does not judge. The renderer, sole owner of presentation and the single choke point at the hardware. The static table, which is the vocabulary and is the only place a new state can be added.

Collaborations

Bounded by One Ordering, One Place: a named state still has to lose to a status signal, and the vocabulary says nothing about rank. Priced by Cap the Decoration, which is what this capability costs.

Consequences

Gain: the safety property is a property of the protocol, so it holds for every producer including ones written later by someone who never read this. Gain: the palette can be retuned without touching the agent. Cost: the agent cannot express something the vocabulary lacks, and adding a word is a deliberate act with a review attached. Trap: the relay must not re-validate: a second copy of the policy is a second thing to keep in step, and it will not be kept in step.

Implementation

Lookup returns an optional over a static table; an unknown name is refused and the known list logged, never approximated to the nearest match. Treat the obvious near-misses as clears (off, none, clear, normal, default), because the agent side maps a model's word onto the wire, and a missed mapping would see a literal off refused as unknown while both halves believed they had agreed.

Failure signature

Nothing at all. The relay here shipped matching the wrong key. It sent type where the contract, written in the same session, specified t. The line arrived, matched nothing, fell into the catch-all and did nothing: no error, no log, no lamp. It was found by review rather than by test, and the reason there was no test is worth carrying: the renderer-facing wire is pinned byte-for-byte, but the agent-facing wire is a different boundary and had none. A pass-through event is precisely the kind that cannot report its own absence.

How you would know this is unnecessary

If the actuator were incapable of harm (a display that physically cannot strobe), or if agent output were reviewed by a person before reaching the hardware. The rule exists because the actuator is in the room, the agent is unsupervised, and the failure mode is not recoverable by noticing it afterwards.

Related patterns

Realises Ambient Activity Channel (OM-001, 9). Bounded by One Ordering, One Place (5). Priced by Cap the Decoration (7). Shares its logic with Constrained Choice (OM-001, 6), one level down: there the closed set protects the person from an unbounded prompt, here it protects the room from an unbounded actuator.

Reproduced from OM-004 · the canonical entry, which this catalogue does not replace.

Ambient Signals · Pattern 4

Deference at Rest

Intent

A person acting directly on a shared device overrides the agent. The agent notices by comparing what the device reports against its own last command, which it can only do while it is idle; during activity there is no single command to compare against.

Motivation

The lamp has other controllers: a vendor app, a schedule, a switch. One was observed changing state on its own mid-session, which is also why capture-and-restore was rejected: it would have fought whatever else was driving it, and a renderer restoring what it captured is indistinguishable from a renderer with a bug.

So the renderer watches for its commanded state and the device's actual state disagreeing, and treats the disagreement as a person. But it can only do that at rest. A live cue repaints every frame; comparing observed state against a moving target registers a mismatch almost immediately, and agent control would suspend itself permanently within seconds of the first conversation. The at-rest restriction is not a shortcut — it is what makes the feature possible at all.

Applicability

Any actuator with more than one controller, one of them a person who cannot be asked what they meant.

Structure

A poll compares the device's reported state against the renderer's last commanded state, but only through an accessor that returns nothing unless the renderer is idle. That accessor is the pattern: the comparison is not disabled during activity so much as undefined, because during activity there is no single commanded state to compare against. A mismatch drops the current decorative state and refuses new ones for a cooldown.

Participants

The renderer, which yields. The device, which reports its own state and is the only witness. Other controllers (a vendor app, a schedule, a switch), which are not observable and do not announce themselves. The person, who is inferred, not detected.

Collaborations

Bounds Closed Vocabulary: a named state can be dropped by a hand, so the vocabulary's guarantee is about what may be asked for rather than what will be shown. Deliberately does not bound Verified Presence or any live cue, for the reason under Consequences.

Consequences

Gain: the agent yields without needing to be told, and without the person learning a gesture. Cost: a poll, and a cooldown that is a guess. Trap: the suspension covers decorative states only, and must. Dimming a lamp by hand is a preference about the room; it is not a wish to stop being told the agent is unreachable, so the states that report agent health keep running. Cap the Decoration (7) draws that same line under a different pressure: here a hand on the device, there the hour of the night. Two unrelated pressures landing on one boundary is the best evidence available that the boundary is in the right place.

Implementation

Poll device status every 20 s against the last commanded state; a mismatch drops the current scene and refuses new ones for 30 minutes. Gate the comparison on an accessor that yields nothing unless the renderer is at rest, and put the gate in the accessor instead of at each call site, so a future caller inherits it without knowing it exists.

Failure signature

Two outcomes, and they look nothing alike. Without the pattern: a person turns the lamp down and the agent turns it back up, which reads as the machine arguing. With the pattern but without the at-rest gate: agent control switches itself off permanently a few seconds into the first conversation, and the layer appears to have died of its own accord.

⚠️ This has never been confirmed against a real hand on the device. Everything above is what the mechanism does, not what has been watched happening, and the untested part is the one that matters: that a person’s intervention is reliably distinguishable from the device drifting on its own.

How you would know this is unnecessary

If the renderer were the only controller: no vendor app, no schedules, no physical switch. Worth checking rather than assuming, since the second controller is usually the one nobody remembers installing.

Related patterns

Bounds Closed Vocabulary (3). Shares its cut with Cap the Decoration (7). Ranked by One Ordering, One Place (5). Yields to the person in the sense Approval Gate (OM-001, 10) formalises, with the difference that there is no gate to pass through; the person acts on the world and the machine notices.

Reproduced from OM-004 · the canonical entry, which this catalogue does not replace.

Ambient Signals · Pattern 5

One Ordering, One Place

Intent

A single-channel surface can show one thing, so the order of precedence is the design, and it has to live in one place a person can read in five seconds, or it is not a safety property at all.

Motivation

Ambient Activity Channel says the renderer owns a priority stack, singular. What was built has two, in two structures of different shape: an if/else chain over time-to-lived live cues, and a separate sequence of early returns for the resting look, reached only when no live cue is active. Neither can see the other. No test asserts the composite.

And the written composite is wrong at its first step. The documentation recorded presence-off > live cue; the code executes live cue > presence-off, because the resting chain is never reached while a cue is live.

The code is probably right: if a cue is arriving then something is demonstrably happening, so nobody is listening is stale information. That is not the point. The point is that two people could each change one structure, each preserve their own invariant, and break the joint one, and nothing would say so.

Applicability

Any channel narrow enough that states compete for it, which is every peripheral channel, since being single-channel is close to the definition.

Structure

Participants

The states, which compete. The ordering, which should be one artifact and here is two. The test, which should assert the composite and here asserts each half. The document, which described a composite nobody could check against the code.

Collaborations

Ranks everything on the channel: Verified Presence, Closed Vocabulary's named states, Darkness as Alarm and the live cues alike. Darkness as Alarm depends on this ordering specifically: it is only an alarm if nothing decorative can outrank it.

Consequences

Gain: an alarm cannot queue behind a flourish. Gain: decoration cannot outrank a status signal, which is what makes a decorative layer safe to add at all. Cost: every new state must be placed, and placing it is a safety decision, not a formatting one. Trap: the ranking split across two structures, which is the state this instance is in.

Implementation

One ordering, one expression, and one test that asserts the composite order end to end rather than each half separately. The test is the part that is easy to skip and is the whole pattern: two correct halves with no joint assertion is exactly the configuration that fails silently.

Failure signature

Nothing visible for a long time, then a state that should have been unmissable does not appear, and the reason is in neither structure. Both halves review cleanly. The person's experience is an instrument that was reliable until the day it was not, with no change to the code that owns it.

How you would know this is unnecessary

If the channel could carry more than one state at once without ambiguity: two devices, or a surface with room for a second mark. That is exactly what the multi-lamp question opens, and it is not obviously an improvement: see §18, where the first thing a second lamp breaks is this pattern's guarantee.

⚠️ This entry's own instance fails it, and it is published that way deliberately. The split was found by looking rather than in review, and the documented composite had been wrong at its first step for a fortnight while every party believed the ranking was the safety model. A pattern demonstrated by its reference implementation falling short of it is worth more than one demonstrated by a tidy listing.

Related patterns

Corrects Ambient Activity Channel (OM-001, 9), whose a priority stack is singular in the prose and plural in the practice. Bounds Closed Vocabulary (3). Ranks Verified Presence (2) and Darkness as Alarm (6).

Reproduced from OM-004 · the canonical entry, which this catalogue does not replace.

Ambient Signals · Pattern 6

Darkness as Alarm

Intent

Keep the resting state lit, so that the channel's most perceptible transition, to zero, is reserved for the one condition worth interrupting for.

Motivation

Peripheral vision is rod-dominated: acutely sensitive to luminance change, poor at hue. A violet-versus-amber distinction beside the monitor has to be looked at, which is the one thing a peripheral channel is supposed not to require. Brightness is also the only ordered dimension the channel has — more is more, with no legend to learn. So the largest signal available is going dark, and there is exactly one of it to spend.

What made it spendable was deleting the mode. While the resting glow meant Agent mode is selected, dark meant dictation far more often than it meant broken: the commonest state in the day occupied the loudest signal on the channel and drowned the only one worth having. Once the chord carried the intent (one chord dictates, another talks to the agent), there was no mode to be in, presence became reachable and not paused, and the lamp is normally on. Darkness became rare, and rare is the whole mechanism.

The question the glow answers moved with it, from is she listening? to could I talk to her right now? That is the question you have before pressing a key, and therefore the one an always-on surface should be answering.

Applicability

A peripheral channel with one ordered dimension, in a space that is normally lit, where exactly one condition warrants interruption.

Structure

Presence is three-valued, not boolean, and the third value is what makes the pattern work. No producer has ever reported (an older client, a scripted replay) falls back to the configured ambient behaviour exactly as before. Reported and off goes dark. Reported and on is the resting glow. So darkness is only ever asserted, never defaulted into, and silence is a distinct state from absence.

Participants

The resting glow, which must be quiet enough to live beside all day. Darkness, the single spendable signal. Silence (no producer), which must not resolve to darkness. The room, whose ambient light level the signal is measured against.

Collaborations

Relies on Verified Presence: darkness means unreachable only because reachability is actually checked, and without that probe this pattern asserts something nobody measured. Ranked by One Ordering, One Place, since an alarm that can be outranked is not one. Protected by Cap the Decoration, which is why a scene cannot paint over an unreachable agent and leave the room looking healthy.

Consequences

Gain: the alarm needs no legend, no colour memory and no focus; it works from across the room and out of the corner of the eye. Gain: it costs nothing extra (no second device, no second mark, no screen). Cost: the resting state must be on, continuously, which makes the resting look a real constraint, not a flourish; here a dim violet-white slow breath at the lowest brightness the device offers. Cost: you get one alarm, and a second condition deserving interruption has nowhere to go. Trap: the room must be normally lit; the signal is a luminance change, so in a dark room it inverts and there is nothing to spend. Trap: silence must not be darkness.

Implementation

Make the third value explicit in the protocol rather than inferring it from a timeout. That distinction is what lets darkness carry meaning while staying backward compatible, and it has a safety consequence beyond compatibility: had silence resolved to dark, the alarm would fire on a missing producer rather than on the condition it names, and the first thing anyone would learn is to ignore it.

Failure signature

An alarm that has been taught to mean nothing. Every spurious darkness spends a little of the only signal there is, and the spending is invisible: nobody records the moment they stopped looking.

⚠️ Nobody has been in the room, not expecting it, when the channel actually died. That the alarm is unmissable is the claim this entry rests on and the one nobody has been in a position to check.

One accident points the right way and is offered as no more than that. The thinking state was originally ended when the reply arrived rather than when playback did; because a reply exists some seconds before it is audible, the lamp went dark at the moment it should have been saying nearly there. It was noticed at once in use, treated as a defect, and closed by adding a state to cover the gap. That is not evidence that darkness alarms. It is evidence that a spurious darkness is not tolerated, which is the discipline this pattern demands of whoever holds it.

How you would know this is unnecessary

If a second condition deserved interruption. The moment there are two alarms, the loudest signal has to be shared, darkness stops naming one thing, and a legend comes back. Also unnecessary where the resting state cannot be on (a channel that is off by default has no darkness to spend), or in a room that is normally dark, where the whole polarity inverts.

Related patterns

Specialises Ambient Activity Channel (OM-001, 9). Relies on Verified Presence (2). Ranked by One Ordering, One Place (5). Protected by Cap the Decoration (7). Resolves Mode Visibility (OM-001, 2) by removing the mode rather than displaying it: the pattern asked that a mode be visible at the moment of use, and the answer that worked was to have no mode.

Reproduced from OM-004 · the canonical entry, which this catalogue does not replace.

Ambient Signals · Pattern 7

Cap the Decoration

Intent

Constrain an ambient channel's decorative output by context and exempt its status output from the constraint, so that carrying decoration never becomes a reason to switch the whole channel off.

Motivation

An agent that can name a scene can name a bright one at 2am. The obvious defence is a global brightness ceiling by hour. It is simple, and it is wrong, because it caps the alarm too. Capping decoration is protective; capping a status signal is breaking it quietly. An error you cannot see at 2am is exactly the failure this layer exists to prevent.

So the clamp is applied at one point (a decorative state's brightness on its way to the device), and conversation cues pass it untouched. They last seconds, they are responses to something you just did, and they are the entire reason the channel is trusted at all.

Deference at Rest (4) draws the same line under a different pressure. There it is a hand on the lamp that suppresses decoration and leaves the status signals alone; here it is the hour. Two unrelated pressures, and the boundary lands in the same place both times, which is the best evidence available that it is the right boundary and not a convenience.

Applicability

Any ambient layer carrying both decoration and status signals, whose acceptable intensity varies with a context the layer can observe: hour, occupancy, a presentation, a meeting.

Structure

One clamp, on one path. Decorative states pass through a brightness ceiling that is a function of context; status states reach the device by a route that has no ceiling on it. The two paths are separated at the point where a state is classified, not at the point where it is drawn, so a new state cannot reach the device without someone having decided which kind it is.

Participants

Decorative states, which are capped. Status states, which are not. The context (here, the local hour), which is read, not configured. The classifier, which is the only place the distinction exists and therefore the only place it can be got wrong.

Collaborations

Prices Closed Vocabulary: this cap is what that capability costs, and the design is that the price is charged to decoration alone. Must not reach Darkness as Alarm or any live cue. Shares its cut with Deference at Rest: both draw the line between decoration and status, and neither lets a limit on the first reach the second.

Consequences

Gain: the layer stays on at night. Without the cap the honest choice is to disable the whole thing after hours, which disables the alarm; the decorative capability would have cost the status signal. Cost: two classes of output now exist and every new state must be classified, silently wrong in both directions: a capped status state is unreadable at night, an uncapped decorative one a light in your eyes. Trap: a clock reading that fails toward day lifts the cap instead of applying it. See Implementation, where the failure direction is the detail worth copying. Trap: the boundaries are guesses. The hours and the ceiling are unmeasured, a fixed window is wrong for a household on other hours, and it is wrong twice a year.

Implementation

Clamp decorative brightness between 22:00 and 07:00 local, on the decorative path only. The window wraps midnight, so it is a union, not a range, and writing it as a range is the obvious bug.

The detail worth copying is the failure direction. The structure the clock is read into is zeroed before the call, and a zeroed structure reads as hour 0 — inside the night window. If the call does nothing whatsoever, the cap engages rather than lifts. A cap that fails open is not a cap.

Failure signature

Not a bright light at 2am; that one announces itself. The failure that costs you is the other direction: someone reasonably decides the layer is too much at night, switches it off wholesale, and the alarm goes with it. Nothing then reports that the channel has stopped reporting, because a channel that is off reports nothing by definition.

⚠️ Never observed at night. Nobody has recorded whether the ceiling is right, and the decision to leave conversation cues uncapped is untested in exactly the case it exists for; no one has watched an error state arrive at 2am and judged whether it read.

How you would know this is unnecessary

If the layer carried no decoration. A channel that only ever reports state has nothing to cap, because every state on it is a status signal and a status signal you cannot see is broken. The cap exists because Closed Vocabulary let decoration onto the channel. The test is therefore not is the cap working but is there anything decorative here at all, and if the answer is no, both patterns go together.

Related patterns

Prices Closed Vocabulary (3): this cap is what that capability costs. Shares its cut with Deference at Rest (4). Must not reach Darkness as Alarm (6). Ranked by One Ordering, One Place (5).

Reproduced from OM-004 · the canonical entry, which this catalogue does not replace.

Revised Output · Pattern 1

Draft and Record

Intent

Let a fast, cheap pass show the person something immediately, and let one authoritative pass produce the text that is kept, and never let the first become the second by default.

Motivation

Two things a person wants from a live transcription are in direct conflict. They want to see words while they are still speaking, which requires a model small and fast enough to run at a cadence. They want the text that survives to be correct, which requires a model good enough to be slow. Building one thing that tries to be both produces a system that is neither: too slow to feel live, too weak to trust.

The resolution is not a compromise but a division. The scribe streams at roughly 50 ms and is understood by everyone, including the person reading it, to be provisional. The corrector runs once, at release, over every captured sample, and its output is the record.

What makes this a pattern rather than an implementation note is that building it stated it more purely than the design did. The system had grown a third thing, the corrector running continuously during the hold, producing accurate text mid-utterance. It looked like the best of both. It is neither the draft nor the record: at release the corrector discards any pass still in flight and issues one fresh pass over the whole buffer, whose text replaces everything the continuous stream produced. The continuous pass cannot change the final text, by construction: there is one buffer, one write site, and one author of the record.

So the record has exactly one author, and anything else in the pipeline is a draft whatever it costs.

Applicability

Any surface where a fast approximate result and a slow correct one are both wanted, and the correct one is what gets stored, sent or acted on.

Structure

Participants

The scribe, fast and provisional. The corrector, slow and authoritative, run once. The buffer, which is what the corrector reads. The record, which has one author by construction, not by convention.

Collaborations

Requires Churn Is Not Correction, because a provisional view that shows every revision is unreadable. Presented by Show the Handover. Structurally enforced by Draft and Record Apart, which is the storage half of the same rule.

Consequences

Gain: the person sees something immediately without the system having to defend the accuracy of what they see. Gain: the record has one author, so which pass produced this? always has an answer. Cost: two models, two code paths, two failure modes. Trap: a third pass that is neither draft nor record, arriving because it looks like an improvement on both. That is exactly what happened here, and it was the most expensive thing in the pipeline while producing nothing that survives.

Implementation

Give the record exactly one write site. Make the draft visibly provisional instead of merely labelled as such. When a pass is in flight at the moment of release, discard it rather than reconciling it: reconciliation is where a draft becomes a record by accident, and it is always the more reasonable-looking of the two options.

Failure signature

The person proof-reads a draft that is about to be replaced, and edits it. They are correcting text that will not survive, and the system gives them no reason to suspect it.

How you would know this is unnecessary

If one model were both fast enough to stream at a cadence a person reads as live and good enough that its output needed no second pass. The gap is not close to closing: the pass accurate enough to keep is an order of magnitude slower than the one that feels live, and it grows with the length of what was said. That is a gap to re-check rather than a permanent condition.

Related patterns

Elaborates Streaming Turn (OM-001, 3). Governed by Honest Gauge (OM-001, 12). Requires Churn Is Not Correction (4). Enforced by Draft and Record Apart (7).

Reproduced from OM-004 · the canonical entry, which this catalogue does not replace.

Revised Output · Pattern 2

No Frozen Prefix

Intent

In a surface that revises what it has already shown, never treat any part of the visible text as settled, because the reviser does not, and a frozen prefix will eventually be wrong in a way the system cannot repair.

Motivation

The obvious optimisation for a live-revising view is to freeze text once it has stood for a while: past some depth or some age, stop re-rendering it. It saves work, it stops the display flickering, and it is the first thing anyone proposes.

Practice says it cannot be done safely, and the story of how it says so is part of the entry. We looked at a spell of short utterances, saw nothing reach far back, and concluded that a deep revision does not happen. Then we watched one rewrite the first word of a long one. What we had looked at was not evidence of absence; it was too short to contain the case.

So there is no depth and no age at which freezing is safe. There is only a frequency: from more than fifteen hundred logged utterances, well under one percent run to thirty seconds at all, which bounds how often the deep case can arise without bounding how deep it goes.

Applicability

Any view that displays output while it is still being revised: live transcription, streaming generation with correction, incremental parsing surfaced to a person.

Structure

The buffer is the truth and the view is a function of it, recomputed. There is no incremental patch path, because a patch path is where a freeze rule would live even if nobody meant to write one. Suppression of visual churn belongs in presentation and is Churn Is Not Correction's job; it must not be implemented by making a revision unrepresentable.

Participants

The reviser, whose reach is unbounded in principle. The buffer, which records every pass. The view, which is recomputed, not patched. The optimisation, which is the antagonist and arrives as a rendering concern, not a semantic one.

Collaborations

Governs Show the Handover. Constrained by Churn Is Not Correction, and the two pull against each other on purpose: the display must be able to show a deep revision, and should usually decline to.

Consequences

Gain: the display can never contradict the buffer. Gain: no class of revision is silently undisplayable. Cost: the whole visible text is re-rendered on every pass. Trap: freezing introduced as a rendering optimisation rather than a semantic decision, by someone who does not know it is one, which is the normal case, since it looks like a performance change.

Implementation

Re-render from the buffer instead of patching what is on screen. If flicker is the real complaint, address it in presentation instead of by bounding what the reviser is allowed to say.

Failure signature

A rare, unreproducible wrongness. The visible text and the system's own record disagree, in the small fraction of cases where the reviser reached past the freeze line, and because the case is rare and long, it is the hardest kind to reproduce deliberately and the easiest to dismiss as a mistranscription.

How you would know this is unnecessary

If the reviser were monotonic: only ever appending, or only ever revising within a bounded window it declared. Neither is true of this corrector, and a system that claims the first should be tested for it rather than believed, because the test is cheap and the failure is silent. Note what the corpus for that test has to contain: utterances long enough to exhibit a deep revision. A corpus of short ones will return a clean null and mean nothing.

⚠️ This entry's reference instance is proposed for deletion. The pattern governs the live view, and the live view is what the 15 August evidence recommends removing. The entry does not die with it. The claim is about live-revising surfaces generally, which is why this language is deliberately not named for dictation; the exemplar goes, and saying so is what the added field exists to enforce.

Related patterns

Governs Show the Handover (3). Constrained by Churn Is Not Correction (4). Elaborates Streaming Turn (OM-001, 3) and Honest Gauge (OM-001, 12).

Reproduced from OM-004 · the canonical entry, which this catalogue does not replace.

Revised Output · Pattern 3

Show the Handover

Intent

When a fast draft gives way to an authoritative pass, make the moment visible, because a person who cannot see the handover will read the draft's errors as the system's errors.

Motivation

In a two-pass surface the text changes twice for different reasons. It changes within the draft, because the scribe is revising its own guess. It changes at release, because a different and better model has replaced the whole thing. These look identical on screen and mean opposite things: the first is a system working, the second is a system finishing.

A person who cannot tell them apart draws the wrong conclusion in both directions. They lose confidence in a correct final pass because they watched it churn on the way there, and they trust a draft because it stopped moving.

The handover is also where the timing argument lives. The corrector's continuous stream runs a cadence plus an inference behind the microphone, and it usually has not caught up with what was said by the time you stop saying it. Against a draft that keeps pace, that is a different kind of feedback, not a slower one. Presenting them as the same channel is the error this seam makes visible.

Applicability

Any surface where two producers of different quality write to one visible region.

Structure

One visible region, two producers, and a presentational distinction that is a property of the region, not an annotation on it. The distinction has to survive being seen at the periphery of attention, because that is where a person reading their own dictation is: they are speaking, not reading.

Participants

The draft and the record, which write to the same place. The seam, which is the presentational fact that they are different. The person, who is not looking directly at any of it.

Collaborations

Governed by No Frozen Prefix: there is no point marking a handover in a view that cannot honestly show what changed. Presents Draft and Record. Requires Draft and Record Apart, in the strict sense that you cannot show a handover between two things that are the same thing.

Consequences

Gain: draft errors are attributed to the draft. Gain: the final pass gets read as final. Cost: a visible transition is a design problem; done badly it is a flash that draws the eye at the exact moment attention should be moving on. Trap: marking the handover so subtly that it satisfies a review and communicates nothing.

Implementation

Distinguish the two states in the presentation itself instead of with a label. Make the transition legible at a glance and at the periphery of attention.

Failure signature

A person who has quietly stopped trusting a system that is working correctly. They watched it churn, drew a conclusion about its accuracy, and the conclusion is wrong, and because nothing failed, there is no incident, no report, and nothing to investigate.

How you would know this is unnecessary

If the draft and the record were close enough in quality that mistaking one for the other cost nothing. That is the perception question again, and it is the one the evidence names as its own falsification test: someone in a blind comparison preferring the hold with continuous correction to the hold without it. Nothing here measures taste, and this entry is honest that its central claim rests on it.

⚠️ Renamed before publication, from The Visible Seam. Seam is already OM-001's template field (which side of the harness/agent boundary a pattern sits on), and two meanings for one word, both ours, is exactly what a plain name is for. ⚠️ This entry's reference instance is proposed for deletion, for the same reason as No Frozen Prefix and with the same consequence: the pattern survives, the exemplar does not.

Related patterns

Governed by No Frozen Prefix (2). Presents Draft and Record (1). Requires Draft and Record Apart (7). Elaborates Honest Gauge (OM-001, 12).

Reproduced from OM-004 · the canonical entry, which this catalogue does not replace.

Revised Output · Pattern 4

Churn Is Not Correction

Intent

Distinguish text that is being corrected from text that is merely oscillating, and stop showing the second: a value alternating between two readings is not information, it is the display leaking the model's uncertainty.

Motivation

Watching a live-revising surface, the eye is caught by movement and infers meaning from it. Most of that movement carries none. The deepest revisions we watched were all the same thing: one word alternating between two spellings of the same sound, never settling: a model equivocating, rendered as though something were being fixed.

And the two scale against each other, which is what makes the entry usable rather than an anecdote: a revision reaching back only a moment is almost always a genuine correction, and one reaching back a long way is almost always a word oscillating between readings it has already tried. The deep revisions that make freezing unsafe (the ones No Frozen Prefix exists for) are almost entirely oscillation, and the two facts have to be held at once: the display must be able to show a deep revision, and should usually decline to.

That is why this is a separate pattern rather than a note on that one. They pull against each other and the resolution is not a compromise: represent everything, present selectively.

Applicability

Any incremental display whose producer revises. The deeper the revision it must support, the more it needs this.

Structure

Participants

The buffer, which records every pass including the ones nobody sees. The per-position history, which is what makes a return detectable. The presentation, which is the only thing that suppresses.

Collaborations

Constrains No Frozen Prefix and is constrained by it in turn. Required by Draft and Record, whose provisional view is unreadable without it.

Consequences

Gain: movement on screen means something again. Gain: the person stops proof-reading a draft that is going to be replaced. Cost: a suppression rule is a judgement, and a wrong one hides a real correction. Trap: suppressing by rate rather than by return; a fast correction is still a correction, and an oscillation that alternates slowly is still churn.

Implementation

Judge by whether the value has returned to one it already held at that position, not by how often it changes. Hold a short history per position instead of a global change counter. Let the buffer record every pass; only the presentation suppresses. The first transition still shows, because that one is news; a word finding genuinely new readings keeps reporting.

Failure signature

A signal fired often enough to be ignored, after which the real corrections it exists to show go past unseen. This is the general failure of any highlight keyed on changed rather than on changed to something new, and it degrades quietly: the indicator keeps working exactly as specified while ceasing to communicate.

How you would know this is unnecessary

If the reviser's intermediate states were themselves worth reading: a system whose second guess is reliably better than its first, rather than one alternating between two guesses of equal confidence. That is measurable, and it was measured here: it is not the case.

Related patterns

Constrains No Frozen Prefix (2). Required by Draft and Record (1). Governed by Honest Gauge (OM-001, 12).

Reproduced from OM-004 · the canonical entry, which this catalogue does not replace.

Revised Output · Pattern 5

Deterministic Last Mile

Intent

Put the last corrections in a table rather than in a model, because the last corrections are not about accuracy at all: they are about convention, and a convention has no uncertainty for a model to resolve.

Motivation

After a biased recogniser has done its work, two kinds of error remain, and they are not the same kind of thing.

The first is acoustic. Several project terms were missed at every boost weight and on both a synthesised and a human voice: words the model does not resolve from the signal, where no amount of weighting invents audio that is not there. Nothing downstream can repair those, because the information never arrived.

The second is orthographic, and it is not an error the model could have avoided. A speaker says workshop machines; the house writes workshop-machines. Both are correct English renderings of the same sound. The model has no way to prefer one, because the preference is not in the audio; it is a house decision, made once, that applies every time. That is the last mile, and it is deterministic by its nature, not by an optimisation.

So the pass that closes it should be a substitution table: microseconds, identical every time, incapable of inventing anything, and printable in full.

Applicability

Any pipeline where a probabilistic stage is followed by a house convention the stage cannot know: orthography, casing, project vocabulary, units, citation style.

Structure

A pure function between the model's output and the destination. It holds no state, consults nothing, and its entire behaviour is a list that can be printed on demand, which is the property that makes it reviewable without reading the source, and is worth building in from the start instead of adding it when someone asks what it does.

Participants

The table, half derived and half hand-written. The matcher, which is whole-word and case-upgrading only. The log, which prints every edit that fires.

Collaborations

Requires One List, Two Uses: the derived half of the table comes from the same vocabulary the recogniser is biased with. Runs strictly after the record exists, so it is inside Draft and Record's record path and never touches the draft.

Consequences

Gain: the whole behaviour can be read as a list rather than inferred from outputs. Gain: no latency and no new failure mode; a table cannot hallucinate. Gain: adding a term is a data change. Cost: it is silent, and a rule firing on the wrong word produces a wrong edit that looks like a correct one. Trap: a case-only rule on an ordinary English word, the sunshine outside becoming the Sunshine outside. Half the project vocabulary here is ordinary English, so case-only rules are refused by derivation and hand-written one at a time instead.

Implementation

Match whole words only. Only ever upgrade case, never downgrade. Never let the pass empty an utterance — typing nothing is indistinguishable from a dead microphone. Print every edit that fires, so the pass is reviewable from its output and not only from its source.

Failure signature

An invisible wrong edit. The text is fluent, plausible and not what was said, and it appears at the cursor in someone else's document. Unlike a mistranscription it carries no acoustic excuse, so the reader attributes it to the writer.

How you would know this is unnecessary

If the convention were already in the recogniser's output — which is what would happen if the vocabulary were boosted as written rather than as spoken, or if the surface being typed into applied the convention itself. Both are real alternatives and neither was tried.

Note what rarity does and does not settle. This pass fires on a small fraction of what is said, and a rule that fires rarely is not thereby unnecessary: the edits it does make land in commit messages and issue titles, where the difference between two spellings is the difference between prose and a link. But the pattern’s case cannot be argued from how often it fires, and an entry that quoted a rate as though the rate were the argument would be arguing the wrong thing.

Related patterns

Requires One List, Two Uses (6). Elaborates Draft and Record (1). Governed by Honest Gauge (OM-001, 12).

Reproduced from OM-004 · the canonical entry, which this catalogue does not replace.

Revised Output · Pattern 6

One List, Two Uses

Intent

Keep one vocabulary file and let both the thing that hears and the thing that writes read it, so a term learned once is learned in both places and cannot be half-learned.

Motivation

A project's jargon has to reach two consumers that look unrelated. The recogniser needs it as bias terms, so the domain words are candidates it will consider. The house style needs it as substitutions, so those words are written the way the house writes them. Maintained separately, the two drift, and the drift is invisible, because each list is individually correct.

The list earns its place: with it the recogniser gets the project’s own words right far more often than without. But the weight it is given has a cliff in it. Modest boosting helps, more helps a little more, and past some point it is worse than no boosting at all: the model begins hearing the boosted words in places they were never said. Over-boosting does not plateau and decay; it inverts.

Applicability

Any system where the same domain vocabulary is needed by a recogniser, a generator and a formatter: speech, OCR, autocomplete, a linter and the model it corrects.

Structure

One file, two derivations. A term containing a separator has exactly one plausible spoken form, so the substitution rule can be computed from the entry instead of written beside it; a term that is an ordinary English word yields no safe rule and must be refused. The effective table is printable, so what actually fires can be compared against what the file says, which is the only way to notice that the two have parted company.

Participants

The list, which is a source, not a deployment. The recogniser, which wants it short, because boosting has a cliff. The formatter, which wants it complete. The copies on disk, which are the actual failure surface.

Collaborations

Required by Deterministic Last Mile, whose derived rules are exactly this list's separator-bearing terms. Elaborates Durable Memory: a shared vocabulary is the system remembering what its domain is called, and it decays the same way.

Consequences

Gain: one place to add a term. Gain: the two consumers cannot disagree about what the vocabulary is, only about what to do with it. Cost: one file becomes load-bearing for two subsystems with different failure modes and different tolerances. Trap: the file is a source, not a deployment. One source with two copies on disk is two lists.

Implementation

Derive instead of duplicating. Refuse to derive case-only rules. Make the effective table printable. And resist the obvious defence discussed below (a hand-written duplicate of the derivable half), or if you must, put an expiry on it.

Failure signature

The two uses fail asymmetrically, and that is the whole of the pattern's danger. The house style can be hand-immunised against a stale list, because a substitution is a decision someone can write down. The recogniser cannot: a term is either in the file it reads or it is not, and there is no hand-written fallback for hearing. So a divergent copy degrades the system in exactly one direction and reports nothing — still spelling the word correctly, no longer able to hear it. The transcript is identical on every utterance where it still hears, which is most of them.

⚠️ The immunisation ate the pattern, and it is visible on the machine today. Of the 18 rules the deployed binary reports, exactly one is derived from the shared list. The other seventeen are hand-written. The source explains why, and was right when it was written: which terms were derivable depended on which checkout's copy of the file was present, and a rule that appears and disappears with a file is worse than no rule.

That justification has since expired (both checkouts now carry the same 47 terms), and what it left behind is a hand table that still rewrites speech into the name of a repository renamed two days before publication, which the shared list has correctly dropped. The defence against drift is now the only thing drifting. The claim survives its instance and is sharpened by it: one source, two mechanisms, no drift possible is a claim about the file, never about the filesystem, and a hand-written fallback added to protect one consumer from a stale list will outlive the staleness and become the stale thing.

How you would know this is unnecessary

If the two consumers wanted different vocabularies. The recogniser wants what is said; the house style wants what is written. Those coincide only while a project's jargon and its orthography are the same words. The moment the boost list needs entries that are never written, or the style needs rules for words never spoken, one list is a coincidence being maintained as a principle.

Related patterns

Required by Deterministic Last Mile (5). Elaborates Durable Memory (OM-001, 14). Governed by Honest Gauge (OM-001, 12).

Reproduced from OM-004 · the canonical entry, which this catalogue does not replace.

Revised Output · Pattern 7

Draft and Record Apart

Intent

Give the draft and the record separate storage, and make the boundary explicit, because the moment they share a buffer, the cheap one becomes the authoritative one by accident, not by decision.

Motivation

Draft and Record says the record has exactly one author. This is the structural half of that, and it is a different claim: not one pass writes the record, but the two passes do not read the same thing.

Here they do not. The scribe consumes a stream as it arrives; the corrector consumes a captured sample buffer with exactly one write site, inside the hold loop. The boundary falls at the buffer, not at the model, which is not where anyone looking at a two-model pipeline would expect to find it, and is why it can be crossed without touching either model.

It was crossed. A 300 ms pad of trailing room tone was added because it recovered dropped final words 6 times out of 6, and it is fed to the scribe's stream and never to the corrector's buffer. So the release pass, the only thing that produces the text that gets typed, sees audio up to the last in-loop drain and nothing after it. The measurement that justified the pad was taken on the path whose output is discarded whenever the corrector succeeds.

That single fact is the pattern's justification and its indictment at once. The separation is exactly what stopped a draft-side change leaking into the record. It is also exactly what let a fix land on the wrong side of the line and stay there, with a measurement attached, looking done.

Applicability

Any two-tier pipeline where a fast stage and an authoritative stage consume the same upstream source: transcription, incremental compilation, preview renderers, any cache in front of a system of record.

Structure

Two artifacts, one write site each, and the count is the invariant. Everything that must reach both is written twice, deliberately and visibly; everything that reaches one by accident is a defect that the structure makes findable and the absence of the structure would make invisible.

Participants

The upstream source, which both consume. Two buffers, which are the pattern. The fallback, which is the one sanctioned crossing and deserves to be named as one.

Collaborations

Elaborates Draft and Record. Required by Show the Handover: you cannot show a handover between two things that are the same thing.

Consequences

Gain: no accidental promotion, ever, and which pass produced this? has a structural answer, not a conventional one. Gain: you can reason about what each consumer actually saw, which is what makes the pad defect statable at all. Cost: anything that must reach both has to be written twice, and nothing checks that it was. Trap: an improvement applied to whichever buffer is easiest to reach from where the change is being made.

Implementation

One write site per artifact, and keep it that way. The count is checkable in a line. When something must reach both, make the two writes visible at the same call site instead of in two files. And name the crossing you do allow: here the release pass falls back to the scribe's text when it fails, which is the one deliberate place the record is written by the draft. It currently reads as a default, not a decision, and the two are worth distinguishing, because the fallback is a real trade: the draft is complete but worse, the last good corrector pass is better but missing the tail.

Failure signature

A fix that works, is measured, is shipped, and changes nothing, because it landed on the path whose output is discarded. Nothing fails. The measurement is real. The improvement never reaches the artifact anyone keeps, and the only way to notice is to trace which buffer the change touched.

How you would know this is unnecessary

If the draft and the record consumed the same input by construction — one buffer with two readers, so there is nothing to keep in step. That is available here and was not chosen, and the reason is worth being honest about: nobody decided. The two buffers grew out of the two libraries' interfaces, and the pattern is a description of an accident that turned out to be right for reasons its authors had not considered.

Related patterns

Elaborates Draft and Record (1). Required by Show the Handover (3). Governed by Honest Gauge (OM-001, 12). Related to Recoverable Execution (OM-001, 13), which is the same instinct about state one level out.

Reproduced from OM-004 · the canonical entry, which this catalogue does not replace.