How to Write and Audit a Note

Braindump

This note is for AI agents. It is the operating procedure every principle note points at — THE set of rules to follow when editing or auditing one of them. This note is their canonical source: where a principle note still carries its own audit instructions, what is stated here supersedes them.

Intellectual honesty

The honest reading is the answer, even when it is thinner than hoped; overreading a source to reach a neater result is advocacy, not reporting. The why behind a choice is the easiest thing to fake — a plausible justification reads almost exactly like a real one — so it is always a real one: when the reason is not known, that is said, or asked.

Epistemic modesty

You are the worst-positioned reader of your own work: the bias that chose a quote reads it as supporting more than it does. So you cannot verify yourself — an independent party must; the audit loop below operationalizes this. A conclusion earns trust only by surviving an attack — what would show it wrong — not by going unchallenged. So the move is active: before concluding X, go looking for what would establish not-X — the warrant for X is the weakness of that case, not the absence of a search for it. Calling a question settled is itself such a conclusion: it earns trust only by surviving the case that the question is still open.

Doubt is recorded, not hedged: « some say », « it is generally accepted », « I believe » let an unsourced claim wear the costume of a sourced one. A note that ends in cited, unresolved disagreement is finished, not failed.

Everything stated is verified, or said to be unknown — no invented ID, fact, or source; a placeholder is a lie shaped like a link.

The audit loop

Self-review fails — the bias that wrote a passage reads it as supporting more than it does — so the verifier is a different party from the author. Spawn it with the spawn_auditor tool, which bakes these rules in. One buddy serves the whole session; holding its principles spares a reload each pass, and the respawn’s re-read catches any you have since edited.

This gate comes before the work, not after it. On any task the first move is to spawn the buddy and plan-gate your opening action. The test-driven baseline run is an action like any other: you state it to the buddy and get GO, and the baseline is then the first gated step — not a move that runs ahead of the gate.

One fix per vetting call — batched reviews coast past the outlier. Each pass is a full audit of the patched passage against every rule, not « does this fix it? ». Audit for objective flaws — subjective battles never end — and surface them all in one pass, not piecemeal. Use the model the work needs — not Opus for a straightforward command.

An ambiguous or conflicting principle is the user’s call, not the buddy’s to guess; surfacing it is one of the ways these principles evolve.

Escalation procedure: how to run an adversarial debate.

Continuous improvement

A bad tool is fixed, not worked around: surface it to the user and fix the tool itself. A workaround hides the defect and ships it again next time; tools improve by being reported — the same reflex that sends an ambiguous principle back to the user rather than guessing.

A note has a shape

A human reads it top to bottom, following one thread, so it needs a shape: past seven sibling headings at one level, or two hundred lines in one section, split into a deeper level. Depth lets the reader hold the whole and place each part; a flat pile has no shape to hold, and an oversized section buries its thread.

Say it in the fewest words — and in diagrams

Fewer words is the default. Anything with the form of an argument, a sequence, a system, or an interaction is a diagram, not prose — even when small. What remains is prose: the why, the bare rationale, which has none of those forms.

argument — reasons, objections, a conclusion — an Argdown map (typed relations).
sequence, system, interaction — a plantuml diagram, rendered inline (the picture, not the source, is what the reader sees).

A rule states what to do, not what to avoid — a don’t X is a scar of a correction; write the positive it implies, or cut it when the structure already prevents X.

Konubinix' opinionated web of thoughts