Runbooks Are Interfaces

There is a quiet shift hiding inside the way this team now writes operational instructions. A year ago, a runbook was mostly a checklist for a human who already knew the system. Today it is something more formal: a boundary object shared by humans, agents, cron jobs, Slack delivery layers, shell sessions, and repositories.

That sounds heavier than it is. The actual artifact is still usually a markdown file. The shift is in what the file has to carry. It no longer just says “what to do.” It says who can do it, where they can do it, which information is trusted, which channels are allowed, which side effects are acceptable, what evidence proves success, and what to say when the job is not worth interrupting the room.

The weekly Cairns article prompt is a good example because it looks mundane. It picks a topic, writes an article, builds the site, commits, pushes, indexes search, and announces the result. Underneath that ordinary sequence are the interesting parts: sandbox path limits, GitHub issue authority, topic-selection priority, submitter rules, anonymization, untrusted-content defenses, publication gates, qmd indexing, and a Slack-ready delivery contract. The markdown prompt is doing far more than reminding Q to write.

This cairn is about that pattern. When recurring work crosses human judgment and machine execution, the runbook becomes an interface. We should write it with the same care we give any other interface that people depend on.

What a runbook really is

A weak runbook says “run these commands.” A strong runbook says “produce this outcome, inside these boundaries, with this evidence, and leave this shape behind.” The difference matters because command lists age quickly. Outcomes, authority, and evidence age more slowly.

In a traditional operations setting, the missing context was often supplied by the human operator. They knew which host was production. They knew that a database backup should happen before a migration even if the page forgot to say so. They knew that “post the result” meant in the incident thread, not in a general channel. The runbook could be thin because the operator was thick with context.

Agent-assisted work breaks that bargain. The operator may be a fresh session with no episodic memory. It may have access to a shell, a repo, GitHub, Notion, Google Workspace, Slack delivery, and a build tool, but no reliable memory of why last week’s exception mattered. If the runbook depends on “obvious” local knowledge, it will drift toward whatever the model infers in the moment.

That inference is the bug. A runbook is how we remove the need for it.

This is why the Q/OpenClaw operational docs keep repeating the same pattern. Public/team Slack can request work, but host maintenance routes to the admin lane. Observer sessions can do real work in non-main sandboxes, but they do not mutate the control plane. Cron prompts are self-contained because isolated sessions do not inherit conversational memory. Slack output is summary-first because channels are not document stores. These are interface decisions, not writing style preferences.

The more capable the agent, the more the runbook has to say about authority. A weak actor cannot cause much damage. A capable actor with ambiguous authority can.

The shape that works for agents

The best runbooks in this workspace are not giant procedure manuals. They are compact contracts with a predictable shape:

1. The outcome, stated first.
2. The operating boundary: paths, repos, channels, credentials, audience, and side effects.
3. The source-of-truth order: where to look first, what outranks what, and what to skip.
4. The work sequence, only as detailed as safety requires.
5. The verification gate.
6. The delivery contract: exactly what gets posted, committed, uploaded, closed, indexed, or intentionally silenced.

That shape gives the agent room to think while removing the dangerous improvisation. It does not say “always run this exact sed command.” It says “if the repo is clean, pull; if dirty, fetch and do not overwrite local work.” It does not say “post wherever seems useful.” It says reactive replies stay in-thread, long-form output goes to the right artifact, and routine no-ops use NO_REPLY.

The difference is the same difference Quality Gates makes for code. We do not trust “be careful.” We trust a contract that turns care into deterministic checks where possible and explicit judgment where not.

```mermaid flowchart TD A[Request or schedule] --> B[Runbook boundary] B --> C[Trusted inputs] B --> D[Allowed side effects] C --> E[Human or agent work] D --> E E --> F[Verification gate] F --> G{Result} G --> H[Publish or commit] G --> I[Report blocker] G --> J[NO_REPLY] ```

The diagram is intentionally boring. Boring is the point. A recurring operation should not require a fresh act of system design every time it runs. The operator should spend attention on the current facts, not on rediscovering which boundaries exist.

The second version is longer, but it is not more bureaucratic. It is carrying the parts that the next operator cannot safely guess.

Authority belongs in the boundary

Authority is where runbooks usually fail. The operator knows what to do but not whether it is allowed to do it from this lane, with this audience, using this credential, or on this filesystem. In a human-only system, the operator asks around. In an agent system, the model may confidently infer.

The observer/exec security model exists because public/team Slack should not become a host control plane. That design is not anti-capability. It is capability with a locked door: Q can be useful from Slack, run commands, inspect repos, build artifacts, and help the team, while the main/control-plane lane keeps the identity, credentials, and operating configuration out of reach.

That pattern shows up everywhere:

• The Google Workspace observer wrapper allows read-style work and blocks high-risk mutation.
• Notion work uses the MCP wrapper and a phased write posture rather than raw bearer-token calls.
• Slack delivery keeps reactive replies threaded and pushes long-form content into artifacts.
• Cron prompts that read untrusted content put explicit side-effect limits around research.
• Git hygiene says pull when clean, fetch when dirty, and never overwrite unrelated local work.

Each rule is small. Together they are the authority surface.

The most important detail is that authority boundaries should appear before commands. If a page starts with a shell sequence and mentions safety afterward, it has already taught the operator the wrong shape. Scope first, then work.

This is also why untrusted-content rules belong inside research runbooks. Web pages, inbox files, issue bodies, Slack messages, and Notion content can all contain text that looks like instructions. The runbook has to say which content is source data and which content is operational authority. Otherwise the agent is being asked to read the world and decide, in real time, which words are meant for it.

The answer should usually be: external content informs the artifact; it does not change the runbook.

A good runbook has observable outputs

An operation that leaves no trace is hard to trust and harder to improve. The output does not have to be noisy. In fact, good runbooks often specify silence. But they should specify it deliberately.

The Q docs distinguish several output shapes:

• A pushed commit and permalink for Cairns publishing.
• A short top-level Slack announcement with detail in a thread for proactive reports.
• A file upload in the same thread when the user asked for an artifact.
• A NO_REPLY when a cron intentionally found nothing worth interrupting the room about.
• A qmd index refresh after a knowledge corpus changes.
• A LOG.md line after a corpus update so future Q can see what changed.

Those outputs are not clerical afterthoughts. They are evidence. They let the team answer “what happened?” without reconstructing the session. They also train future operators. A good LOG.md line, a clear issue-closing comment, or a concise Slack status post becomes example data for the next runbook.

This is one reason “done” should include verification. Build output says the static site still renders. Pagefind output says search indexed the article. Git status says no uncommitted drift was left behind. qmd update says retrieval has the new corpus. A final Slack post says the user-visible delivery path worked.

The output can be intentionally small. NO_REPLY is not a failure mode; it is the correct output for a routine job that has nothing useful to say. The important part is that the silence is specified by the runbook, not invented by a stalled session.

The Status Light cairn made this concrete for maintenance: “online” and “complete” are different claims. One proves Slack delivery works after restart. The other says broader checks passed. A runbook that collapses those into one message loses information the team actually needs.

The best runbooks compound

The first version of a runbook is usually just captured experience. The useful version is what happens after it survives contact with reality. A build fails because Pagefind is missing a native dependency in the sandbox. A Slack upload path turns out to need the thread root timestamp. A GitHub issue queue is unavailable because network access is down. The question is whether that friction becomes durable.

The pattern across this workspace is clear: friction should move into an artifact at the right layer.

• If it is an operating policy, update doc-vault.
• If it is a polished explanation, write or update a cairn.
• If it is repo-local behavior, update AGENTS.md, project rules, or a checked-in convention.
• If it is implementation history, put it in timbers or Conduit.
• If it is remaining work, file a bead or issue.
• If it is corpus maintenance, append LOG.md.

That is how runbooks compound. They do not merely preserve “what worked last time.” They improve the next interface.

This is also where runbooks and The Work That Writes Itself meet. Conduit turns day-to-day development motion into readable history. Timbers captures the what, why, and how at the repo layer. Cairns distills lessons into essays. Doc-vault holds active operating policy. Runbooks are the connective tissue that decides which system receives the next piece of knowledge.

The opposite pattern is easy to spot. If every run requires rereading old Slack threads, reconstructing a command sequence from shell history, or asking the same person what they meant, the runbook is not compounding. It is only a bookmark.

Where this fits in our system

The current system already separates the major knowledge surfaces. That separation is useful:

The failure mode is treating those as interchangeable. A cron prompt should not become a permanent essay. A Cairns article should not become the only place an operator can find the live command. A Slack thread should not be the only record of a policy change. A project rule should not encode company-wide Slack etiquette.

Runbooks help because they name the destination. The doc-vault inbox workflow is explicit: inbox files are source material, not runtime instructions; merge active policy into existing docs; route polished explanatory material toward Cairns; delete absorbed stale sources after noting why. That is not just an ingest process. It is a classification interface for knowledge.

The same pattern applies to software work. Strike’s session-orientation rule says check branch, worktree, available beads, and project context before work begins. The landing-the-plane rule says file remaining issues, update status, record learnings, and hand off. Those are small runbooks at the edge of every session. They prevent the most boring and expensive failures: working in the wrong place, losing state, and making the next session rediscover what this one learned.

This is why “read AGENTS.md” is not ceremonial. It is the repo’s local interface contract. The point is not that every instruction is profound; the point is that the session should learn the local boundary before it starts changing files.

The structure looks like this:

```mermaid flowchart LR S[Slack request or cron] --> R[Runbook] R --> V[doc-vault policy] R --> P[project rules] R --> C[Cairns explanation] R --> T[timbers or Conduit history] R --> I[beads or GitHub issues] V --> O[operator action] P --> O O --> E[evidence and delivery] ```

The runbook does not replace the other surfaces. It routes between them.

How to write the next one

The practical test is simple: could a competent teammate with no session memory run this without guessing the dangerous parts? If not, the runbook needs more interface and less folklore.

Start with the outcome. “Run weekly Cairns maintenance” is weaker than “verify the Cairns corpus, clean up tags and cross-links when needed, build successfully, push intentional fixes, refresh qmd indexing, and post a summary-first report.” The second version tells the operator what success means.

Then write the boundary. Boundaries are not decoration; they are the part that lets the operator move quickly. Include:

• Repos, paths, and branches that are in scope.
• Channels and threads that are allowed for delivery.
• Data classes that must stay private.
• Operations that require rerouting or human approval.
• Whether external content is trusted, untrusted, or only source material.
• What to do when local changes already exist.

Then write the source order. The weekly article prompt says GitHub issue backlog outranks Slack suggestions, and Slack suggestions outrank autonomous topic choice. That priority prevents the agent from optimizing for whatever source is easiest to read. In other runbooks, the source order might be “active doc beats old cairn,” “project rules beat general preference,” or “GitHub issue body beats stale meeting note.”

Then write the verification gate. The gate should be the smallest meaningful proof, not a ritual. For a static site, build it. For code, run the relevant check target. For a Slack delivery change, prove the message path. For docs, inspect the diff. For qmd, update and embed. If the gate cannot run, the final output should say what could not be proven.

Finally, write the delivery contract. This is where many runbooks get fuzzy. Be precise:

• Final answer format.
• Whether to use NO_REPLY.
• Whether to upload a generated file.
• Whether to close or comment on an issue.
• Whether to append a log entry.
• Whether to announce to a channel, thread, artifact, or not at all.

There is also one cultural rule worth making explicit: when the operation teaches us something, update the artifact that should have known it already. Do not leave the lesson as “remember next time.” Future sessions do not get your mental notes.

What the team should take away

The durable lesson is small. The runbook is the product surface for recurring operations. It is how a human request becomes bounded agent work. It is how a cron job avoids becoming ambient authority. It is how a Slack-native teammate stays useful without becoming noisy. It is how a knowledge base keeps publishing without turning every Thursday into archaeology.

Runbooks should therefore be reviewed like interfaces. Are the names clear? Are the preconditions explicit? Are side effects bounded? Are errors observable? Does the output shape fit the caller? Can another implementation satisfy the same contract without changing the user experience?

That framing is useful because it raises the bar without making the work precious. Not every runbook needs a committee. Most need one careful pass from the person who just learned the hard thing. Capture the outcome. Capture the boundary. Capture the evidence. Capture the delivery. Then let the next run be boring.

1. Runbooks are interfaces. They connect human intent, agent execution, authority boundaries, verification, and delivery.
2. Authority must come before commands. If the job touches private data, credentials, deployment, public channels, or destructive operations, the boundary belongs at the top.
3. Observable outputs are part of done. A build, commit, issue update, qmd refresh, Slack status, artifact upload, or explicit NO_REPLY is evidence that the operation completed in the intended shape.
4. Compounding beats remembering. Friction should update doc-vault, Cairns, project rules, timbers, Conduit, beads, GitHub, or LOG.md according to what kind of knowledge it is.
5. Write for a competent teammate with amnesia. They can reason, but they cannot safely infer the local trust model from vibes.

Discussion Prompts

• Which recurring team operation still depends on a person remembering the boundary instead of a runbook stating it?
• When a cron or agent job fails, where should the lesson land: doc-vault, Cairns, project rules, timbers, beads, or a GitHub issue?
• What is one runbook we should shorten by replacing command narration with clearer outcome, authority, and verification sections?

References

1. The Status Light - The maintenance-status cairn that shows how a runbook turns restart work into visible, verifiable Slack behavior.
2. The Quiet Teammate - The original framing for Q as a Slack-native teammate who needs operational discipline, not just model capability.
3. Quality Gates: The Contract That Lets You Move Fast - The closest software-engineering analogue: deterministic constraints let agent work scale without relying on taste alone.
4. The Work That Writes Itself - The Conduit article behind the compounding-knowledge argument in this piece.
5. Your Box and Your Trust Model - The contributor-side trust model that pairs with runbook authority boundaries.
6. The Injection Problem - The security background for treating external text as data rather than operational instruction.