The governing document

Governing document — TEMPLATE

Copy this file, fill it in, delete the guidance blocks. The guidance is indented under each heading in > quotes so it is obvious what is scaffolding and what is content.

Two rules about filling it in:

A section you cannot answer stays `UNRESOLVED`. It does not get a plausible answer. A governing document with a confidently invented approval threshold is worse than one with a blank, because a blank stops someone and an invention gets followed. UNRESOLVED is a legitimate state for a draft; it is not a legitimate state for a promoted version.

Every constraint here becomes at least one eval case. See fixture-derivation.md. A constraint with no case behind it is decoration — it reads like governance in a review and does nothing at runtime, which is the worst of both. If you cannot describe the case that would fail, the constraint is not yet written precisely enough.

0. Identity

The owner is the person who answers for this agent's decisions. Not the engineer who deployed it. If nobody will put their name here, that is the finding, and it outranks everything else in this document.

1. Scope

This agent decides:

One sentence per decision. A decision, not a capability. "Classifies whether a line item exceeds the HUD allowable for its work type" is a decision. "Analyzes invoices" is a capability and cannot be tested.

This agent does NOT decide:

Harder and more important than the list above. The boundary is where agents do damage: not by doing their job badly, but by doing an adjacent job nobody authorized. Name the neighbouring decisions it will be tempted to make — especially the ones a reasonable reader would assume were included.

2. Source of authority

Authoritative corpus:

What it must reason from, precisely enough to point at. "HUD Handbook 4000.1, Section III.A.2, as published" — not "HUD guidance."

Citation requirement:

Whether every substantive claim must carry a locator, and what a locator looks like. If the answer is yes and there is no case testing it, the requirement is aspirational.

When the corpus is silent or ambiguous:

The single most common failure in regulated work is an agent smoothing over a gap in the source with general knowledge, fluently. Whatever the required behaviour is — escalate, return not-addressed, cite the nearest governing text and flag the distance — write it here and test it.

Corpus freshness:

How the agent knows the corpus is current, and what it does when it cannot tell. An agent quoting a superseded schedule with total confidence is not a smaller problem than one quoting nothing.

3. Inputs

Receives:

May look up:

Must never look up or accept:

Third block matters most. It is where scope creep enters — an agent given a general search tool has a much larger effective scope than its document describes, and no amount of prose in section 1 constrains that.

4. Actions and reversibility

Every action the agent can take on the world. Reading is not an action here; writing, sending, paying, filing, scheduling, and notifying are. A table containing only reads is a complete and good answer. An advisory agent that classifies and escalates, and lets a human do everything else, is the safest shape there is, and this section is where that becomes visible rather than assumed. Say so explicitly — the first real agent this template was run against turned out to be entirely read-only, and the fact was nowhere in its existing governance because nobody had a place to write it down. "Reversible" means reversible in practice by the people who will be there, not reversible in principle by an engineer with database access at 2am. An email that has been read is not reversible. A payment that has cleared is not reversible. Be pessimistic; the cost of wrongly calling something irreversible is one extra approval step. Every irreversible action needs a named approval, and the record must be able to show which approval authorised which action. An approval granted during a different run is not an approval for this one.

5. Escalation

This agent MUST stop and hand to a human when:

1. 2. 3.

Write each as a predicate that could be evaluated, not a sentiment. "When confidence is low" is untestable and will be quietly ignored. "When the line item's work type does not appear in the allowable schedule" is testable, and a case can be built for it in a minute. Each of these becomes at least two fixtures: one that must escalate, and one deliberately near the boundary that must NOT. Testing only the first direction teaches an agent that stopping is always safe, and you end up with something that escalates everything and gets switched off for being useless.

What it hands over: (what the human receives — enough to act without redoing the work)

Who receives it:

6. Refusals

Out of scope requests, and what it says:

Distinct from escalation. Escalation means this is our work and a human must decide it. Refusal means this is not our work. Conflating them buries real escalations in a queue full of people asking the invoice agent about payroll.

7. Output contract

Shape:

Required fields:

Every output must carry:

At minimum: the decision, the governing document version in force, and the locator for anything asserted about the corpus. The version stamp is not optional and is not reconstructable afterwards — it is stamped at write time or it does not exist.

8. Failure modes

Fill in every row. These are the situations where an ungoverned agent invents, and they are cheap to test. Most production incidents live in this table.

8b. Runtime bounds

Added after the first real run through this template. The agent had a step budget of 12 — a genuine governance parameter, since a loop without a ceiling is an unbounded spend and an unbounded latency commitment — and there was nowhere in the document to record it, so it lived only in a constant. The right-hand column is the part that gets skipped. An agent that exhausted its step budget mid-analysis is not the same as one that failed, and a record that files both as "error" cannot tell you which happened. Note also where a schema constraint is not really enforced. If the provider rejects part of your output schema and the bound is applied in code afterwards, the code is the control and this is where that gets written down.

9. Data handling

Must never be logged:

Must never leave the environment:

Retention:

10. Calibration

Cost asymmetry:

Which is more expensive here — a wrong answer, or an unnecessary escalation? Answer in the domain's own terms, with roughly the ratio. This single answer sets every threshold in the document, and it is the question nobody asks. An agent tuned as though both cost the same will be wrong in whichever direction the model happened to lean.

Expected escalation rate: (with a tolerance band)

A number and a range. This becomes a standing drift alarm: an agent that declared 15% and is running at 2% has stopped escalating, and its evals will not tell you, because each individual run looks fine. Both directions are alarms. Silence is the one that hurts.

11. Unresolved

Everything the owner has not yet decided. Each with the question, who owes the answer, and what the agent does in the meantime. A document with entries here is promotable only if the interim behaviour for each is itself safe and tested. Usually that interim behaviour is "escalate." Split the table by who can actually answer. Running this template against a real agent made the split the most useful thing in the document: questions the author can close this afternoon are a task list, and questions that need the operations org are a meeting agenda. Merging them into one column hides which is which, and the second group is the one worth carrying into a room.

Answerable by the author

Requires the organisation

12. Review

"Why" is the column that gets skipped and the only one anyone needs later. The question asked six months from now is never "what changed" — a diff answers that. It is always "why did we think that was safe at the time."