Skip to content

docs(corpus): define the runbook corpus template - #1527

Merged
tucktuck101 merged 1 commit into
launchpadfrom
task/1347-corpus-template-runbook
Aug 28, 2026
Merged

docs(corpus): define the runbook corpus template#1527
tucktuck101 merged 1 commit into
launchpadfrom
task/1347-corpus-template-runbook

Conversation

@serina-mcfall

@serina-mcfall serina-mcfall commented Aug 27, 2026

Copy link
Copy Markdown

Closes #1347

Issue type

Task

Node

corpus-template-runbook at launchpad/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 describes
a policy/standard node, not a template. This node is built against #605's
actual acceptance criterion instead:

Every template states its purpose, required sections, evidence expectations
and the industry model/standard it adapts.

The document has a Purpose section, a Required sections section (six
numbered sections a runbook instance must carry, each traced back to the SRE
Workbook's playbook definition), an Evidence expectations section, and
The industry model this adapts section naming the Google SRE Workbook by
name and URL. A Note on this issue's definition of done at the top of the
document states this mismatch explicitly so a reviewer doesn't wonder why
there's no MUST/SHOULD section.

type chosen and why

type: governance. Checked node.schema.json, schema/README.md and
schema/COMPATIBILITY.md myself — the type enum has 13 members and no
template or policy value. Every merged corpus meta-document about how to
author
corpus content (AGENTS.md, standards/confidence.md,
standards/decision-references.md) uses governance; this template is the
same 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 enum
and 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/corpus myself (not assumed) — at this revision the merge
target carries exactly four authored nodes: corpus-agents, corpus-readme,
corpus-standard-confidence, corpus-standard-decision-references. None is
topically about runbooks. corpus-agents would resolve as a references
target today, but standards/confidence.md and standards/decision-references.md
both 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 omissions section, 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, branch
docs/research-project-doc-templates) — cited as TEAM_KNOWLEDGE with
provided_by naming the PR, never as FACT, since it's unmerged research and
not 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 definition
    quote and the "if it's a deterministic list of commands, automate it
    instead" caveat verbatim. Cited as FACT in this node's own ledger,
    separately from the TEAM_KNOWLEDGE citation of the note.
  • https://sre.google/sre-book/example-postmortem/ — confirmed the
    postmortem 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

$ python3 -m unittest discover -s launchpad/docs/corpus/schema/tests -p "test_*.py" -v
...
Ran 27 tests in 0.032s
OK

Run as the lone command from this worktree immediately before the commit —
earned the .claude/.verified stamp for this checkout.

$ python3 launchpad/project-intelligence/corpus/validate.py
PASS  corpus validation found no errors; 10 item(s) reported unverified

Exit 0. All 10 UNVERIFIED notices 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 one
tool-result citation for the git ls-tree check I ran myself. None of the 10
are FACT/INFERENCE entries resting only on an unopened source — I opened
every 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 before
committing; checked for stray RFC-2119-style MUST/SHOULD keyword 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.

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 tucktuck101 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.md and README.md both 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 leaving AGENTS.md untouched 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

task: define the runbook corpus template

2 participants