Keep runbooks and incident playbooks up to date
A runbook is read at 3am by someone who did not write it. If the command, path or default on the page no longer matches the code, the page costs time exactly when there is none. Amendary checks runbooks and playbooks against each landed commit and drafts the fix with the commit attached.
What runbook drift looks like
Runbook drift is the gap between what a runbook says and what the system does. It rarely arrives as a rewrite. It arrives as one renamed flag, one moved config file, one timeout that changed from 30 to 60 seconds. The prose around it still reads fine, so nobody notices until the page is followed under pressure.
Code review does not catch it. The runbook sits in a docs folder, a wiki or a Notion page that the pull request never touched.
The two page types
On-call runbook
Prerequisites and access, how to start and stop, health checks, common alerts and what to do about them, rollback, escalation. Written action first.
Incident playbook
One page per known failure mode: symptom, diagnosis, fix, verification, prevention. For the same reader as the runbook.
Both can live in a GitHub docs folder, the repository wiki, or Notion. You can write them yourself and watch them, or have Amendary generate them from the repository. A generated runbook or playbook also reads the repos your pages map as Background only, such as infrastructure or config repos, where the real commands often live. Generation spends credits; the daily checks and corrections are covered by the subscription.
How checks run
- Engineering documentation follows commits on the repository’s default branch. Checks run per landed commit, never per pull request. An open PR is not a check; a merged one is checked once it lands. Checks run daily.
- Only mapped pages are checked. A mapped page is a page you chose to watch and tied to the repository it describes (“Describes this repo”). A repository the page only leans on for background is mapped as “Background only” and does not trigger a check unless you tick “Check when this repo changes too”. A GitHub page maps only to the repository it lives in.
- For a runbook or playbook, a changed command, path, environment variable, default or flag counts as real staleness even when the sentence around it still reads well.
- The draft shows the old text, the new text, and the commit and summary it came from. Every version, path and URL in it has to be grounded, meaning the diff backs it up. Under Apply automatically the risky drafts still wait for a person (see Queue & reviews).
- Drafts wait in the queue, the list of corrections for your review, until you apply or dismiss them. New workspaces start on Review first for Engineering docs and Help center. An applied correction can be undone for 30 days if nobody edited the passage since.
Writing back to GitHub is opt-in
- GitHub writes are off by default. A repository with GitHub docs off is read-only: code is read for evidence and nothing is written.
- A workspace owner enables one target per repository: a folder (
docsby default) or the wiki. - A folder target delivers a correction as a pull request you review and merge (the default) or as a direct commit. An owner can change the folder, branch or delivery later with Edit on the destination. Several corrections can collect in the same open PR. A wiki target is written directly.
- Amendary writes documentation, never application code. A runbook kept in Notion gets a Notion edit, or a comment when the edit cannot be placed on a specific block.
Incident records are history
An incident playbook tells the next person how to fix a known failure, so it should follow the code. A record of a past incident is different. The timeline, the values that were true that day and the decisions taken are history, and rewriting them to match today’s code would destroy the record. Amendary does not rewrite them. Keep postmortems and incident reports unwatched; an unmapped page is never edited. Watch the playbook, not the record.
A sample
This is a step from a runbook Amendary generated for its own backend. It is a sample, not a customer page. A later commit changed the window from 30 minutes to 10, which made the step wrong. This is the kind of correction a check drafts for it.
Recovering a stuck or failed run
Before
A running check whose heartbeat is older than 30 minutes is marked failed and no longer blocks a new run.
After
A running check whose heartbeat is older than 10 minutes is marked failed and no longer blocks a new run.
When Amendary generates a runbook, every command, path and default comes from the repository word for word. A step whose exact command is not in the repository gets a “Needs verification” note rather than a guessed command.
Where to go next
- Daily checksHow each landed commit is checked.
- Generate docsDraft runbooks and playbooks from the repo.
- DiagramsA diagram from the code for a runbook.
- Update GitHub docs after a releaseFrom a landed commit to a docs pull request.
- Document typesRunbooks, playbooks and the rest.
- GitHub integrationRead access, the docs target and delivery.
Try Amendary on your own help center
Connect GitHub and the runbooks you already keep in Notion or a repo's docs folder or wiki. Amendary checks them against each landed commit and drafts fixes with evidence.
Free for 14 days with no card, and every edit waits for your review. Or free forever with your own Anthropic API key. Code is never touched.