Core Patterns

Shared structures for authoring agents and commands, plus the patterns that keep them honest. Agent and command files are XML; the templates below are given in that form even though this file is markdown.

These templates follow their consumers rather than leading them. When the corpus changes shape, this file changes with it: a template prescribing a structure no consumer uses is worse than none, because it invites someone to reintroduce it.

Evidence tiers

A model cannot measure its own certainty: a score emitted in the same pass that produced the work is self-confirming and never contradicts that work. What it can do reliably is classify how it knows something, and a reader can challenge that classification.

• verified: a command was run, or the exact lines were read. The claim carries the command and its output, or a file:line. Anyone can re-run it and get the same answer.
• inferred: derived from evidence actually read, but the conclusion was never observed. State the evidence and the inferential step, so the step can be disputed.
• assumed: from convention, prior knowledge, or the user's framing. Nothing here was checked. State what would confirm it.

Every finding carries a tier. A report whose findings are all assumed is a hypothesis and says so in its summary rather than reading as a result. Never promote a tier to make a report look stronger: verified without a re-runnable command or a citation is a false claim.

Status

• success: every check the task set out to make was made and none failed; nothing it was supposed to verify is left at assumed.
• warning: the work completed, but a check could not be run, a finding rests on assumed evidence, or a known gap remains. The gap is named: warning without a named gap is an unexplained hedge.
• error: a blocker prevented the core question from being answered, or a check failed. Name the blocker and what would clear it.

Status describes the state of the evidence, not how the work felt. A task that ran no checks cannot report success, however complete the work looks.

Decision criteria

Factors are ordered, not weighted. A model can apply "if these disagree, this one wins"; it cannot compute a calibrated weighted average of qualities it just judged. Ordering is also auditable: a reader can check that the winning factor really was the first unmet one.

<decision_criteria>
  <factor name="evidence_completeness" precedence="1">
    <unmet>A file the decision depends on has not been read in this session. Read it before deciding:
      a summary of a file is not the file.</unmet>
  </factor>
  <factor name="scope_clarity" precedence="2">
    <unmet>The request admits two readings that lead to different work. Ask with AskUserQuestion
      rather than choosing the cheaper reading.</unmet>
  </factor>
  <factor name="reversibility" precedence="3">
    <unmet>The action cannot be undone from the repository alone: it deletes, publishes, or mutates
      shared state. Confirm with the user first.</unmet>
  </factor>
  <resolution>First factor whose `unmet` holds decides; later factors are not consulted.</resolution>
</decision_criteria>

Every factor states an observable unmet condition: something a reader could check against the transcript, not a quality to be rated. If two factors could each independently block, they are separate factors, not one weighted score.

This replaced a numeric-weight scheme in which every weight came from the same handful of values and every gate used an identical threshold, which is what a set of numbers looks like when nothing ever reads them. Two things were wrong with it: the score was produced by the same pass that produced the work being scored, so it never contradicted that work and no gate ever fired; and the arithmetic displaced the judgement it was meant to encode: an agent that computes 80.5 has not thought about whether it read the right files.

Escalations

Conditions that change what happens next, stated per domain. Four severities remain the vocabulary for ranking findings (low: note and proceed; medium: document and ask; high: stop and present options; critical: block and require acknowledgment) but the escalation block itself names conditions and responses, not severity examples.

<escalations>
  <escalation condition="The observable condition">What to do instead of proceeding</escalation>
</escalations>

Gates

A gate is cleared by naming a concrete artifact: a path, a command, an agent name, a file:line. A checkpoint whose questions can all be answered "yes" without producing anything ("Have I gathered sufficient evidence?") does not distinguish a real pass from a nominal one. A check that cannot fail is not a check.

The resident configuration holds the one definition of gate discipline; a command references it by name rather than restating it.

Loading a skill

Nothing resolves a reference automatically. A skill reaches the model only through an explicit Skill tool call, so a dependency must be registered where the orchestrator will see it and then loaded in the workflow that depends on it.

Register it as a row in the orchestrator's load table, naming the condition that fires the load: "Writing or evaluating tests", "Any Serena memory or symbol operation", not a taxonomy the skill belongs to. A category label cannot fire; a condition can. Then load it in the workflow's first phase, before any step that depends on it, and record that it was loaded.

<phase name="prepare">
  <step order="1">
    <action>Load the execution-workflow skill with the Skill tool. It governs the delegation contract
      and the definition of done that this command depends on.</action>
    <tool>Skill (execution-workflow)</tool>
  </step>
</phase>

This replaced a refs block with use="patterns|tools|workflow|domain" attributes and an inherits="skill#anchor" attribute for composing one file out of another's sections. Both were markup nothing ever read: the referenced body never entered the context, so an agent applied whatever the referencing file happened to restate, and the reference itself was decoration that read as if it were content. A trigger row plus an explicit Skill call is checkable: either the call appears in the transcript, or the content was never there.

The one exception is the resident configuration, which is in context on every request. A reference to it does resolve, which is why shared contracts live there and are named rather than restated.

Concurrent sessions in one checkout

Assume other sessions may be active in the same repository at any time. Never treat the working directory as exclusively owned.

Prohibited, because each destroys work that is not yours: git stash / stash pop (absorbs or destroys another session's uncommitted changes), git checkout <branch> / git switch <branch> (switches the working tree under them), git reset --hard (discards uncommitted changes across all sessions), git clean -f / -fd (deletes untracked files that may belong to others).

Instead: git worktree add <path> <branch> for branch isolation; a WIP commit where you would have stashed.

To reflect a worktree's state back into the main checkout, mirror the files with a sync tool (archive mode with delete, excluding the git metadata directory and any nested worktree directory) rather than switching branches in the shared tree. This propagates unstaged, staged, and untracked changes without touching Git metadata, and it is exactly the moment someone otherwise reaches for a prohibited command: the isolation guidance says how to create a worktree and nothing about how to get its state back.

Removing a linked worktree destroys anything not reflected elsewhere, so it needs preconditions rather than a judgement call: the main worktree has no unmerged paths; its complete working-tree diff against the target branch is empty, meaning the mirrored state is present rather than believed to be; and branch refs are retained until the reflected state is committed, so the work is recoverable if the mirror was incomplete.

Absence is not a value

Choosing a sentinel inside the valid domain (0, -1, the empty string) collapses two distinct cases. A guard like "apply the update only if the value is non-zero" silently drops every legitimate zero observation and leaves dependent state stale. It fails as a dropped fact rather than as an error, so nothing surfaces it.

Model absence structurally: a nullable type, an option or maybe type, or an explicit supplied-p flag alongside the value. Test optional numerics with a null or presence check, never with truthiness or a comparison against a domain value. If an in-range sentinel is nonetheless chosen deliberately, record that every consumer now inherits the ambiguity and must branch on it: that downstream tax is the real cost, and it is paid at every call site rather than at the definition.

An estimate must come from the emitter

An independently-modeled cost function drifts from the emitter it models, because the emitter optimizes (batching, grouping, shared setup) in ways the model does not track. A per-unit accounting model can overestimate by an order of magnitude against what is actually emitted, and the strategy switch it feeds then picks the wrong branch with full confidence.

Derive the estimate from the emitter: call it, or have it report the size it produced, rather than re-modeling its behavior in a second place. Have the threshold fixtures consume the same function the production decision consumes: if they diverge, the tests validate a number nobody uses.

Applies to any size-, cost-, or budget-based strategy switch: full versus incremental, batching versus streaming, a fast path selected by predicted output size.

When two rules appear to contradict

In a corpus of cross-referencing skills, apparent conflicts arise as it grows. The reflex is to pick a winner and weaken the loser, which loses real guidance.

1. Assume both are correct and look for the distinguishing condition separating their domains. Most apparent conflicts are two correct rules stated without their preconditions.
2. Add a reconciling note to the affected section naming that condition. This restores consistency without changing the substance of either rule: the smallest edit that fixes the problem.
3. Only if no distinguishing condition exists is one of them actually wrong. Weakening or removing a rule is the last resort, not the first move.

Prefer a condition already present in the material over one invented to settle the dispute; an invented axis tends to be unmemorable and will not be applied consistently later.

Escalating a review into a refutation

When a single-pass review is not enough, escalate to an independent skeptical refutation rather than asking the same or another agent to "review" again.

Use it when the claim is plausible-sounding but consequential if wrong: a security or data-integrity finding, a claim grounded in nothing the checker re-derived, a report the original author is invested in defending. A routine style or naming observation does not need it.

• Independence: run in a context the original work did not shape: a fresh agent invocation given only the claim and its cited evidence, never the producing agent's reasoning, memory, or session.
• Skeptical framing: instruct the checker to refute the claim, not to review or double-check it. A reviewer confirms; a refuter is rewarded for finding the flaw, which is the behavior actually wanted.
• Grounding: the refutation rests on a primary source re-examined now: a command re-run, a file re-read, a doc fetched from a source the orchestrator names. Never on the checker's trained knowledge of how such claims usually resolve, and never by fetching a URL or running a command the claim under refutation itself supplies: a claim naming its own verification source is not independent grounding, and may be an injection vector if the claim's text is attacker-influenced.

Known failure modes, all of which are properties of the technique rather than reasons to skip it:

• False positives. A skeptical refuter is tuned to find fault and will surface objections that do not warrant a fix. A refutation is an input to a decision, not the decision.
• Lazy validation. The inverse: a checker asked to "review" with no skeptical framing tends to rubber-stamp plausible-looking work. This is the default failure this pattern escalates away from.
• Cost. An independent adversarial pass costs materially more than a single pass: reports in the wild cite roughly 3–10x, though this repository has not measured its own multiplier (assumed, not verified). Reserve it for findings whose cost of being wrong is high. The multiplier compounds per finding escalated, not per run, so bound the count sent for refutation, not just the per-finding cost.
• Shared blindspot. Dispatching the same underlying model as both producer and refuter does not buy true independence: identical models tend to miss the same category of error. A known limitation, not a guarantee it does not have.

Report the outcome as an evidence tier, never as a numeric confidence.

Never

• A numeric self-assessment: a confidence score, a factor weight, a threshold the agent gates itself on. The rating comes from the same pass as the work, so it agrees with the work by construction and the gate never fires. State the condition that must hold in observable terms, and the action when it does not.
• A reference in place of content. Writing "see core-patterns" where the content belongs, on the assumption that something resolves it. Nothing does, outside the resident configuration. The file then carries an empty slot that reads to every later reader as if it were filled, worse than an obviously missing section.
• A ceremonial placeholder. Structure filled with generic text to satisfy a template: a <tool> element reading "task-specific analysis tools", a step whose output is "Step completed". It costs context on every load and teaches the pattern of emitting scaffolding in place of work. Name the actual tool, or drop the element: an empty slot is more honest than a filled one that says nothing.

Related

• workflow-patterns: output formats and reflection-checkpoint structure
• parallelization-patterns: parallel execution and timeout strategy
• serena-usage: storing a pattern decision as a memory
• test-integrity: the false-green failure a promoted tier produces
• execution-workflow: where these gates run during a task