Skill: Documentation (ADR & Runbook)
Create ADRs and Runbooks for operational documentation.
ADRs
When to Create
- Choosing between technologies
- Significant architectural changes
- New patterns/conventions
- Deprecating approaches
Template
# ADR-[NUMBER]: [TITLE]
**Status:** [Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
**Date:** YYYY-MM-DD
## Context
[Why do we need this decision?]
## Decision
[What is being decided?]
## Options Considered
### Option N: [Name]
- **Pros:** [Benefits]
- **Cons:** [Drawbacks]
## Consequences
- Positive: [Benefits]
- Negative: [Tradeoffs]
- Risks: [Risk] - Mitigation: [How]
Location: docs/adr/ADR-NNN-description.md
Rules: Keep immutable (supersede, don't edit). Index in README.
Runbooks
When to Create
- New service deployment
- Common operational tasks
- Incident response
Template
# Runbook: [Service/Task Name]
**Service:** [Name] | **Owner:** [Team] | **On-Call:** [Contact]
## Prerequisites
- [ ] Access to [system]
## Common Operations
### Start/Stop/Health Check
[Copy-paste-ready commands]
## Troubleshooting
### Issue: [Description]
**Symptoms:** [What user sees]
**Diagnosis:** [Commands]
**Common Causes:** [List with fixes]
## Alerts & Escalation
| Alert | Severity | Action | Escalate After |
Location: docs/runbooks/service-name.md
Rules: Test commands before documenting. Review after incidents.
Checklists
ADR: Clear problem, options evaluated, decision stated, consequences documented, numbered/indexed.
Runbook: Prerequisites listed, commands copy-paste-ready, issues documented, escalation path defined.