amak07/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

| Level | Definition | Review Required | | ------ | ------------------------------------ | --------------- | | Low | No data loss risk, easily reversible | None | | Medium | Potential service disruption | Team lead | | High | Data loss risk, hard to reverse | Team approval |

Output Location

| Category | Output Path | | ----------- | ---------------------------------------------- | | Deployment | /docs/operations/deployment/[name].md | | Database | /docs/operations/database/[name].md | | Maintenance | /docs/operations/maintenance/[name].md | | Incident | /docs/operations/incident-response/[name].md |

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