Migrating existing ops documentation

Audience: you have runbooks in a wiki, a repository, or somebody's notes, and you want them in a form that is searchable now and runnable later.

The honest headline: you do not have to finish. P0 is a real destination, not a waiting room.

P0 first, and P0 may be enough

P0 is your existing prose plus frontmatter. It gets you indexed, searchable, filterable by target and risk, and carrying provenance. Roughly 95% of public runbooks are P0 and stay there, which is why the catalog is built to make them useful rather than to nag them upward (§5).

Add the required metadata, keep your markdown exactly as it is, and stop. Nothing is wrong with the result.

What P1 buys, and what it costs

P1 adds steps[]. In exchange you get static risk checking, capability consistency, a graph a reader can scan — and the ability to run the procedure under supervision, which P0 cannot offer because prose has no execution semantics.

The cost is real: you have to decide what each paragraph is. Most of the work is deciding where one step ends, and most of the value is in having decided.

Lift it one step at a time

Take the procedure's first paragraph and ask: is this a check, an action, a decision, a wait, or an escalation? Those five cover ops procedures, and the constraint is deliberate — five kinds is few enough that the mapping to an execution engine stays unambiguous.

Then:

1. Split anything that does two things. "Check the lag and restart" is two steps.
2. Give it an imperative title, up to 48 characters.
3. For a check, write down what should be true and where you go if it is not. You already knew both; the wiki page just did not have anywhere to put them.
4. Label the risk honestly. This is the field that decides whether a supervisor demands a human.
5. Name the tool. cli:kubectl, mcp:postgres. Anything a command invokes must be declared.

The paragraph that will not decompose

Some paragraphs are context, not steps: why this happens, what it means, who to tell. Those belong in the body, which survives migration untouched. Every record in std/ has one — std/postgres-drop-stale-replication-slot explains in prose that its rollback does not recover released WAL, and no step could carry that.

If a paragraph is genuinely a procedure and genuinely will not decompose, that is information: it usually means the procedure has an undocumented decision inside it.

What to expect from the gates

The first lint will tell you things your wiki never did:

• a command that invokes something you did not declare;
• a destructive step with no gate and no rollback;
• a decision with no default branch;
• a credential you forgot was in an example.

None of these are new problems. They were in the wiki page too — the difference is that something now says so before an agent runs it.

Do not machine-translate the body

If your procedure is not in English, title_en and summary_en are required so that clustering works, but the body stays in its own language. A translation error in a step marked destructive is an incident, not a typo (§16).