Keep Runbooks Executable
Require every runbook to carry real commands, a verification step, a rollback, and an owner.
The worst time to discover a runbook says "then verify it worked" with no command is 3am, mid-incident.
Prompt for your coding agentOpen in Claude ↗
Add mediva to this repo (npm i -D mediva) and write docs/runbooks/_template.mdv.md. Write each runbook so npx mdv check docs/runbooks reports nothing: every step a command, every verification with its expected output.
Starters are being rebuilt; write this by hand.
---
owner: "@platform-oncall"
last-validated: 2026-09-01
---
<!-- mdv: front owner required -->
<!-- mdv: front last-validated required date=iso -->
<!-- mdv: document content.none=@agent/chatter content.none=@agent/cut-off -->
<!-- mdv: section required content.words.min=10 content.none=@placeholders -->
## When to use this runbook
The alert, dashboard reading, or user report that sends someone here — for example, the `RedisDown` page firing for more than two minutes.
<!-- mdv: section required content.blocks.has=code content.none=@placeholders content.none=/sk-(live|test)-[A-Za-z0-9]+/ -->
## Steps
Each step is the actual command, not "restart the service":
```sh
kubectl -n cache rollout restart statefulset/redis
```
<!-- mdv: section required content.blocks.has=code content.words.min=10 -->
## Verification
The command that proves the fix worked, and what its output should say:
```sh
redis-cli -h redis.cache.svc ping # expect: PONG
```
<!-- mdv: section required content.words.min=5 -->
## Rollback
What to do if the steps above make things worse, and who to page next.## When to use this runbook
When Redis has issues.
## Steps
Restart the Redis service and wait for it to come back. If that does not work, restart it
again or escalate to the platform team.
## Verification
TBD
## Rollback
N/Aredis-outage.md
Shape: fix the form; this does not change what the document claims
1 error Missing frontmatter key "owner" missing-frontmatter-key
help: Add the key to the --- block at the top
1 error Missing frontmatter key "last-validated" missing-frontmatter-key
help: Add the key to the --- block at the top
✖ 2 problems (2 errors, 0 warnings)
mdv explain <rule-id> for detailsProse where commands belong, no owner, a TBD verification: exit 1. content. is the rule that bites, and the contract's own body is its worked example.
npx mdv check finds docs/ in CI; a sibling redis-outage. overrides it for one runbook.
Variations
| Want | Do |
|---|---|
| no agent chatter or cut-off output | keep the document content. line |
contracts out of docs/ | . (where contracts live) |