Document Runbook

Runbook Documentation Skill

Purpose

Create operational runbooks for deployment, database operations, incident response, and maintenance procedures. These are "How-To" documents in the Diátaxis framework, specifically for operations tasks.

Smart Interaction

ASK the User When:

• Creating new runbook: Confirm process name and risk level
• Deleting runbook: Always confirm before deletion
• High-risk procedures: Confirm rollback steps are adequate

PROCEED Autonomously When:

• Updating existing runbook: Add new steps, update commands
• Adding troubleshooting: Enhance with new failure scenarios
• Fixing commands: Correct outdated or broken commands
• Adding verification steps: Improve procedure completeness

Documentation Principles (CRITICAL)

Before writing ANY documentation, review ../DOCUMENTATION_PRINCIPLES.md for:

1. Ground Truth Only - Document what exists in code, no speculation
2. Writing Tone - Clear and educational without audience labels
3. Code Examples - Real files with paths and line numbers
4. Performance Docs - Techniques + measurement methods, NOT estimated timings
5. What NOT to include - No troubleshooting, future work, or meta-commentary
6. Diagrams - Use when they clarify technicals, not for decoration

These principles override any template suggestions that conflict with them.

Note: Runbooks are the APPROPRIATE place for troubleshooting content (unlike feature docs).

Instructions

When documenting operational procedures:

1. Identify the process (deploy, rollback, migration, etc.)
2. Use the runbook template at templates/runbook.md
3. Include actual commands that can be copy-pasted
4. Document failure scenarios and recovery steps
5. Output to /docs/operations/[process-name].md

Template

Use the template at: .claude/skills/document-runbook/templates/runbook.md

Runbook Categories

Organize runbooks by category:

docs/operations/
├── index.md                    # Operations overview
├── deployment/
│   ├── deploy-to-production.md
│   ├── deploy-to-staging.md
│   └── rollback-deployment.md
├── database/
│   ├── database-migration.md
│   ├── backup-restore.md
│   └── seed-data.md
├── maintenance/
│   ├── dependency-updates.md
│   └── log-rotation.md
└── incident-response/
    ├── service-outage.md
    └── data-corruption.md

Command Standards

• All commands must be copy-paste ready
• Use environment variables for secrets: $DATABASE_URL
• Include --dry-run options where available
• Show both successful and error outputs

Risk Levels

Output Location

Quality Checklist

Before completing:

• All commands are copy-paste ready
• Expected outputs documented
• Failure scenarios covered
• Rollback procedure included
• Troubleshooting table complete
• Prerequisites clearly listed
• Time estimate provided
• Risk level assessed
• Emergency contacts included (for high-risk)

Examples

Creating New Runbooks (Will Ask User)

• "Create a deployment runbook" → Ask: Risk level? Environment?
• "Document the database migration process" → Confirm category and scope

Updating Existing Runbooks (Autonomous)

• "Add new step to deployment runbook" → Updates existing doc
• "Fix the database restore command" → Corrects command
• "Add troubleshooting for timeout errors" → Adds to troubleshooting table

By Category

• "Document production deployment" → /docs/operations/deployment/deploy-to-production.md
• "Create database backup runbook" → /docs/operations/database/backup-restore.md
• "Write incident response for outages" → /docs/operations/incident-response/service-outage.md