Writing things down
Documents and runbooks
Twenty-two kinds of durable written work, from recovery runbooks and ADRs to PRDs, research notes, SLOs, and style guides.
“save a runbook for restoring the database from backup”
A runbook in your workspace, findable by anyone in it.
“write a postmortem for last night's outage”
A postmortem, drafted from the sessions where you fixed it.
“what's our runbook for a failed deploy?”
The document, not a summary of what one might contain.
Durable documents let you explain an operating reality once. A later assistant can retrieve the current runbook, SLO, design specification, or glossary entry when the task calls for it instead of asking you to paste the procedure into a new conversation.
Runbooks first
A runbook is an operational procedure: deploy, rollback, restore, rotate, recover, or respond. It should be executable under pressure, with prerequisites, ordered steps, verification, failure branches, and a safe stopping point.
write the runbook for restoring the Oregon replica, including how to verify
replication and when to stop and escalateSave the runbook while the procedure is fresh. Link it from the reminder that starts the rotation, the incident where it was used, the handoff that transfers on-call work, and the diagram that explains the failure path.
A runbook you can trust during an auth change
Suppose you are changing authentication middleware after a rate-limit incident. A useful runbook does more than list commands. It tells the next operator:
| Part | What belongs there |
|---|---|
| Purpose and scope | Which service, environment, and failure mode this procedure covers |
| Prerequisites | Required access, current decision, relevant lesson, known-good version, and a clean rollback target |
| Preflight | Confirm the rate-limit path, middleware order, documentation, and tests before touching production |
| Ordered steps | One bounded action at a time, with the expected result after each |
| Verification | The exact health, auth, traffic, and error signals that prove the change worked |
| Failure branches | What to do when a check fails, rather than continuing down the happy path |
| Rollback | How to restore the known-good state and verify that recovery |
| Stop and escalate | Conditions where the operator must stop, plus who or what owns the next decision |
The preflight can point to the decision that explains the middleware order and the lesson from the earlier environment mismatch. The steps should not paste those records into a second copy. Link them, then keep the procedure focused on safe execution.
After the runbook is exercised, record what differed from reality. Update the current procedure, create a ticket for work that remains, and preserve a postmortem when the event deserves a timeline and contributing-factor analysis.
Make an external version deliberately smaller
An internal incident runbook may mention environment variables, internal customer identifiers, debug logs, ticket links, or account names. A client-facing status document should not inherit all of that material.
For an external handoff, keep the status, customer-visible impact, next action, and expected update time. Remove keys, environment values, internal IDs, unrelated customer context, raw debug logs, and internal-only issue references. Use a controlled capsule when the recipient needs supporting context, and inspect its redaction and expiry policy before sending it.
All twenty-two kinds
The kind is not filing trivia. It lets “find the signing-key runbook” return an operating procedure instead of a passing note with the same words.
General and reference
| Kind | Use it for |
|---|---|
| General document | A draft or piece of mixed writing that genuinely fits nowhere more specific |
| Specification | A technical contract for an API, schema, component, or behavior |
| Roadmap | Themes, milestones, and sequencing over time |
| Glossary | Canonical meanings for project terms and overloaded vocabulary |
| Q&A document | A durable question and answer that should be read as a page |
| Style guide | Code, design, writing, naming, formatting, or voice conventions |
Engineering and delivery
| Kind | Use it for |
|---|---|
| Architecture Decision Record (ADR) | Context, choice, alternatives, consequences, and status for a significant architecture decision |
| Request for Comments (RFC) | A technical proposal that needs asynchronous review before it becomes a decision |
| Release notes | The human-readable changes for one release |
| Changelog | A rolling history across many releases |
| Playbook | A repeatable non-emergency process such as onboarding, launch preparation, or demo setup |
Operations and learning
| Kind | Use it for |
|---|---|
| Runbook | A step-by-step operational procedure |
| Postmortem | Incident timeline, contributing factors, impact, lessons, and follow-up work |
| Retrospective | What worked, what did not, and what changes after a sprint or project |
| On-call schedule | Rotation responsibilities and timing |
| Service Level Objective (SLO) | Reliability target, measurement window, error budget, and alert relationship |
Product, design, and research
| Kind | Use it for |
|---|---|
| Product requirements document (PRD) | Problem, users, proposed outcome, boundaries, and success measures |
| User story | One user need with acceptance criteria |
| Persona | A user archetype's goals, jobs, pains, and constraints |
| Interview notes | Customer or user research evidence from one conversation |
| Design specification | Interaction behavior, visual decisions, tokens, edge cases, and rationale |
| Critique | A durable design or code-review write-up and its takeaways |
If a specific kind fits, use it. “General” is a fallback, not the default for every page.
Creating a document from the work
Ask for the kind, subject, and intended reader. For documents based on an incident or past session, tell the assistant which evidence to use and require it to mark any gap rather than fill the gap from imagination.
Good source material can include captured sessions, decisions, incident timelines, tickets, repository history, diagrams, and connected services. The draft still needs review. Recorded context improves the evidence available; it does not turn an inference into a fact.
Linking the record, not copying it
Keep one authoritative document and link it to the work around it:
- an incident can point to its postmortem;
- a release can point to its release notes;
- an experiment can point to its result write-up;
- a plan or ticket can attach a spec, diagram, runbook, or handoff;
- a reminder can point to the runbook it is asking someone to perform.
That chain lets a later assistant move from “what happened?” to “what did we learn?” and “what changed?” without maintaining several pasted copies.
Documents, decisions, answer-base items, and skills
A decision is a focused choice with a history and a superseding relationship. An ADR is the longer architecture narrative around a choice.
An answer-base item is a short piece of guidance, a guardrail, a frequently asked question, a caveat, or a compact operational answer used when answering project questions. A Q&A document is a page someone might read end to end.
A skill is a reusable procedure that can be applied or run. A playbook or runbook explains the process; a skill can make a connected assistant follow it.
Finding, editing, and retiring documents
Ask by kind, title, or subject: “show the runbooks about replication” or “find the ADR where we chose the queue.” You can browse and edit in the dashboard as well.
Documents are Markdown records. Update a document when it remains the current authority. Keep a dated replacement when the historical version matters. Delete a stale duplicate when leaving both would create two apparent answers. Unlike a decision, one document does not automatically supersede another.
If it doesn't work
A document doesn't surface when it should. Check its type. A runbook filed as a general document is a weaker answer to “what's our runbook for…”.
Two documents contradict. Documents don't supersede each other the way decisions do. Delete or update the stale one — nothing does it for you.
A drafted document invented details. It drafts from recorded sessions. If the work happened with capture off, the evidence may be incomplete. Check the sources and label unknowns before you publish.