docs(corpus): define the runbook corpus template - #1527
Conversation
Adds launchpad/docs/corpus/templates/runbook.md, the template a runbook corpus node must follow: purpose, required sections, evidence expectations and the industry model it adapts (Google SRE Workbook's playbook definition), per PRD #605's real acceptance criterion rather than #1347's boilerplate MUST/SHOULD checklist. Closes #1347 Signed-off-by: Serina Mcfall <serina.mcfall@gmail.com>
tucktuck101
left a comment
There was a problem hiding this comment.
Review — runbook corpus template
Both SRE attributions check out as quotations: the deterministic-list recommendation is real (it
lives in the "Maintaining Playbooks" aside, which plain text extraction drops), and SRE Book
Appendix D is indeed the retrospective Example Postmortem — so the decision to keep postmortem and
runbook as separate document types is well grounded. Two accuracy defects and one dead routing
pointer.
High — a FACT states AGENTS.md uses type: governance; it uses type: agent
The entry reads "Every merged corpus meta-document about how to author corpus content — AGENTS.md,
standards/confidence.md, standards/decision-references.md — uses type: governance", and cites
launchpad/docs/corpus/AGENTS.md as its own evidence.
Verified on launchpad: that file's frontmatter is id: corpus-agents / type: agent. Only
README.md, standards/confidence.md and standards/decision-references.md carry governance.
Three sibling templates in this same wave state it correctly — procedure.md:19,
threat-model.md:19, and deployment.md:20 which explicitly reads "AGENTS.md excepted, which is
type: agent" — so this is a single-node error, not a shared misreading. The precedent argument
survives on the three nodes that do carry governance; only the claim's scope is wrong. The same
wording is in the PR body.
Medium — "the chapter is explicit that a playbook is not a script" is not what the source says
:132-140 asserts that, and :141-148 builds a normative instruction on it (documenting one fixed
sequence with no decision point is the wrong use of the template).
I fetched sre.google/workbook/on-call/ and read the "Maintaining Playbooks" passage in full. It
records a disagreement, not a rule:
"Some SREs at Google advocate keeping playbook entries general so they change slowly ...
Other SREs advocate for step-by-step playbooks to reduce human variability and drive down
MTTR ..."
— and the page marks the topic contentious. The automation recommendation is scoped narrowly to the
degenerate case (a deterministic list run every time a particular alert fires), which this node's
own frontmatter entry at :39-42 states correctly. So the ledger is right and the body over-reads
it. Restate the source's actual position.
Medium — the overflow case is routed to a document shape nobody defines
:161-163: "A node that tries to cover 'how to operate service X' in general is either an
operations-type reference node or several runbooks, not one." No template defines an
"operations-type reference node". The corpus template that owns goal-oriented operational
instruction is procedure (#1345, PR #1539), whose own worked example is "operations for a how-to
on rotating a credential". An author following this line is sent nowhere. Name procedure as the
owner.
This is also the runbook side of the missing runbook/procedure boundary — the procedure side omits
runbook entirely. Boundary ruling, unhedged: "cut a relay release" is procedure; "relay is
5xx-ing" is runbook. They are genuinely distinct and there is no duplication; each simply needs
one bullet naming the other.
Low — the cited Workbook chapter is titled "On-Call", not "Being On-Call"
The node calls its source "the Google SRE Workbook's 'Being On-Call' chapter" in FACT statements at
:35 and :39 and in prose at :123 and :232. Workbook Chapter 8 is titled "On-Call"; "Being
On-Call" is Chapter 11 of the first SRE Book, which the Workbook chapter recaps and links. The
cited URL is correct and every quotation is on it, so nothing downstream is affected.
Not findings, ruled out on evidence
- Index registration: the corpus
AGENTS.mdandREADME.mdboth state that indexes are
generated derived views, never hand-authored, and the ten-step "Creating a node" procedure has
no registration step. All 26 template PRs leavingAGENTS.mduntouched is correct. - CI green at head (latest run per check); node validates clean.
Reviewed by tucktuck101's review lane. Every failing claim reported above was reproduced by me against this PR head before posting.
Closes #1347
Issue type
Task
Node
corpus-template-runbookatlaunchpad/docs/corpus/templates/runbook.md.Which of #605's real template criteria this satisfies
Per the shared batch brief, #1347's own definition-of-done checklist is
byte-identical boilerplate copied from the standards-track issues (compare
#1310's DoD, which produced
standards/decision-references.md) and describesa policy/standard node, not a template. This node is built against #605's
actual acceptance criterion instead:
The document has a
Purposesection, aRequired sectionssection (sixnumbered sections a runbook instance must carry, each traced back to the SRE
Workbook's playbook definition), an
Evidence expectationssection, andThe industry model this adaptssection naming the Google SRE Workbook byname and URL. A
Note on this issue's definition of doneat the top of thedocument states this mismatch explicitly so a reviewer doesn't wonder why
there's no MUST/SHOULD section.
typechosen and whytype: governance. Checkednode.schema.json,schema/README.mdandschema/COMPATIBILITY.mdmyself — thetypeenum has 13 members and notemplateorpolicyvalue. Every merged corpus meta-document about how toauthor corpus content (
AGENTS.md,standards/confidence.md,standards/decision-references.md) usesgovernance; this template is thesame kind of artifact (about corpus-authoring practice, not itself an
operational document), so it follows the same precedent.
Separately, the document states that a runbook instance created from this
template should use
type: operations— that value exists in the same enumand is the natural fit for an operational document, which the template itself
is not.
Relationships declared or checked-and-declined
None declared. Ran
git ls-tree -r --name-only origin/launchpad -- launchpad/docs/corpusmyself (not assumed) — at this revision the mergetarget carries exactly four authored nodes:
corpus-agents,corpus-readme,corpus-standard-confidence,corpus-standard-decision-references. None istopically about runbooks.
corpus-agentswould resolve as areferencestarget today, but
standards/confidence.mdandstandards/decision-references.mdboth already declined that same edge, choosing to add the whole cross-corpus
edge set in one later pass once more standard/template siblings land — this
node follows the same practice rather than adding one edge in isolation
against a set still taking shape. No edge to any of the four sibling template
issues in this batch (#1326, #1327, #1328, #1335) either — none of the five
will be merged before review starts on the others, so none of their ids exist
at any plausible merge target yet. All of this reasoning is written into the
node's own
Scope and omissionssection, not just asserted here.Research-note grounding (§4 of the brief)
Grounded in the unmerged research note
launchpad/Research/project-documentation-templates.md(PR #1466, branchdocs/research-project-doc-templates) — cited asTEAM_KNOWLEDGEwithprovided_bynaming the PR, never asFACT, since it's unmerged research andnot an accepted decision.
I did not defer to the note blindly — I independently fetched and read both
primary sources it cites for this row:
https://sre.google/workbook/on-call/— confirmed the playbook definitionquote and the "if it's a deterministic list of commands, automate it
instead" caveat verbatim. Cited as
FACTin this node's own ledger,separately from the
TEAM_KNOWLEDGEcitation of the note.https://sre.google/sre-book/example-postmortem/— confirmed thepostmortem is a retrospective, root-cause/timeline/lessons-learned document,
distinct in purpose from a runbook's real-time prescriptive guidance. Also
cited as its own
FACT.I found nothing in the note that conflicts with what I read at the primary
sources for this row — no correction needed here. The document keeps the
runbook and postmortem boundary the brief specified: there is no postmortem
issue in this batch, and this template does not fold the two together.
Verify-gate and validator evidence
Run as the lone command from this worktree immediately before the commit —
earned the
.claude/.verifiedstamp for this checkout.Exit 0. All 10
UNVERIFIEDnotices are expected: commit-reference citations(the standard provenance entry, present on every existing node too), the
three external-URL citations to the SRE Workbook/SRE Book pages (this
validator can't pin or open non-GitHub URLs — see
AGENTS.md), and onetool-result citation for the
git ls-treecheck I ran myself. None of the 10are
FACT/INFERENCEentries resting only on an unopened source — I openedevery external URL myself via fetch before citing it as
FACT.Cross-model final pass
Codex (the cross-model provider) is down, tracked as #1467. Per the brief,
substituting a same-model adversarial self-review pass instead of a real
cross-model pass — re-read the drafted node against
node.schema.json,AGENTS.md, both standards docs, and the two primary SRE sources beforecommitting; checked for stray RFC-2119-style
MUST/SHOULDkeyword leakage(the document deliberately declines to be normative) and confirmed none
outside quoting/describing the issue's own boilerplate.
Escalations
None filed. No blockers found outside this node's own scope during drafting;
no ambiguity found in the architecture-triad boundary section (not this row's
concern) or elsewhere that warranted a new issue.