2.4 KiB
Runbooks and Architecture Decision Records
Architecture Decision Records
ADRs provide durable reasoning, not only outcomes.
Required sections
- Context
- Decision criteria
- Options considered
- Decision
- Consequences
- Validation
Metadata
- stable ID;
- project;
- human-readable decision number;
- status;
- decision date;
- supersedes/superseded-by;
- owner/author;
- linked page;
- tags.
Lifecycle
- Proposed
- Accepted
- Rejected
- Superseded
- Withdrawn
An accepted ADR can be superseded only by another accepted ADR. Links are bidirectional and cycle-free.
Editing the ADR page creates revisions. Changing lifecycle metadata is audited and revisioned. Historical decisions remain readable.
Runbooks
A runbook is a human-executed procedure. The platform never runs its commands.
Required sections
- Purpose
- Scope
- Prerequisites
- Steps
- Validation
- Rollback
- Risks/notes
Metadata
- owner;
- risk: low/medium/high/critical;
- system/project tags;
- last validated time and validator;
- review due time;
- estimated duration (optional);
- maintenance-window requirement (optional);
- runbook status.
Checklist behavior
Markdown task lists may be used as a transient execution checklist, but checking boxes in a normal read session must not silently modify the canonical runbook.
A future “run session” can create an execution copy, but that is deferred. In v1 the UI may provide a local/non-persistent checklist mode with an explicit warning.
Validation
Marking a runbook validated requires:
- permission;
- current revision;
- validator;
- time;
- optional evidence/comment.
A new content revision makes prior validation stale unless the change is explicitly classified non-procedural and policy allows it.
Safety
- Commands render as text/code only.
- No terminal bridge.
- No secret interpolation.
- No copy button may include hidden text.
- Sensitive-value placeholders are visibly marked.
- High/critical runbooks emphasize prerequisites, validation and rollback.
Templates
Canonical templates live in product/templates/. The application may seed editable
copies, but template version/provenance is retained.
API behavior
ADRs and runbooks are retrievable through their own typed endpoints and through page resources. The context API returns bounded summaries and stable page citations rather than silently parsing arbitrary headings at request time.