[Amendary]

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. 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. 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. An ungrounded value, a removal or an addition waits for a person even in auto mode.
  • Drafts wait in the queue, the list of corrections for your review, until you apply or dismiss them. New workspaces start in review mode. 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 (docs by default) or the wiki.
  • A folder target delivers a correction as a direct commit or as a pull request you review and merge. 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 an excerpt from a runbook Amendary generated for its own backend. It is a sample, not a customer page.

Recovering a stuck or failed run

  1. Check GET /jobs/daily-sync/status. If running: true but started_at is far in the past, the process behind it may have died.
  2. A running row whose heartbeat is older than STALE_RUN_AFTER (30 minutes) is marked failed and no longer blocks a new trigger. Re-triggering /jobs/daily-sync is usually enough to unstick a dead run once it ages past that window.

When Amendary generates a runbook, any command, path or default it could not find in the repository is listed as a warning for you to check, and a step with no exact command in the repository is marked TODO rather than guessed. If that 30-minute window later changes in the code, the correction to this page is what you would see in the queue.

Where to go next

See the first correction on your own docs

Connect GitHub and the docs you already keep in Notion or GitHub. The first check runs on a recent release, so you see a correction with its evidence before you decide anything.

Start freeRead the walkthrough

Free for 7 days, no card. You approve every edit. Code is never touched.