---
name: document-runbook
description: Document CI/CD, deployment, and operational procedures. Use when creating runbooks, documenting deployment processes, or writing operational guides.
---

# 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`