Living Runbooks With Real Citations

PROBLEM Operations runbooks go stale the moment code ships. The engineer who understood the service moves on, and what remains is either missing or quietly wrong. Teams that keep documentation current rebuild it by hand: someone reads the code, then types what they remember. That is slow, unverifiable, and carries no proof, so a reader cannot tell a documented fact from a plausible guess. A wrong runbook is worse than none: during an incident it sends an on-call engineer confidently in the wrong direction. SOLUTION Living Runbook Generator takes a public GitHub URL and produces an operations runbook in which every factual claim is tied to a specific line of code. Four bounded analyzers read the repository: a Service Mapper for routes and entry points, a Failure Analyzer for error handling and retries, a Dependency Mapper for declared libraries and base images, and a Configuration Analyzer for environment variables and constants. Every finding carries a file path, a line number, and the source text at that line. A validation layer checks each citation against the repository before the runbook is written, and a finding that cannot be located in the source is dropped rather than approximated. The output is Markdown, so it lives beside the code and is reviewed like code. HOW IT WORKS The repository is cloned read-only into a temporary workspace that is deleted when analysis finishes. No code from it is executed and no dependency from it is installed. A file allowlist and size ceilings keep the input bounded. Credentials, tokens and private keys are redacted before analysis and scanned for again in the finished document. The analysis is deterministic static analysis rather than a language model guessing from a summary, so the same commit always produces the same runbook. TARGET USERS Small engineering teams and platform maintainers responsible for a service they did not write, who need to know what it does, what it depends on, and how it fails while an incident is in progress. HOW THEY USE IT They paste a repository URL, watch the analysis run, and read the draft. They can ask plain questions, answered only from the runbook itself and cited back to specific lines, and refused when the question asks for a secret or for an action to be performed. The runbook stays a draft. An approver reviews and publishes it; the person who generated it cannot approve their own work, a rule enforced on the server, not the interface. Every security-relevant action is recorded in an audit log. A GitHub Action re-runs the analysis on demand and proposes updates as a pull request, which it cannot merge or publish on its own. WHAT MAKES IT UNIQUE The evidence is the product. A summary can be confidently wrong. A citation cannot be wrong quietly, because it is checked against the source before anyone reads it. The result is a runbook that stays honest as the code beneath it changes, instead of one that drifts.