SpillwaveSolutions/document-specialist-skill / skills/documentation-specialist
documentation-specialist
VerifiedThis skill should be used when creating professional software documentation (SRS, PRD, OpenAPI, SDD, architecture docs, user manuals, tutorials, runbooks) from templates (greenfield) or reverse-engineering documentation from existing code like Spring Boot or FastAPI (brownfield). Also handles documentation audits/reviews, format conversion (Markdown, DOCX, PDF), and diagram generation (Mermaid first: C4, sequence, class, ER, state, flowchart; PlantUML Salt for UI wireframes and leftover UML). Use when asked to "create documentation", "document my code", "write SRS", "generate PRD", "write DESIGN_DOC.md", "architecture document", "wireframe", or "documentation specialist".
references/reference/06-operational-docs.md
View on GitHub# Operational Documentation Best Practices
**Version**: 1.0.0
**Token Budget**: ~400 tokens
**Last Updated**: 2025-01-18
---
## Runbook Essentials
### Purpose
Runbooks enable any authorized engineer to execute complex operational tasks consistently and safely.
### When to Create
- **Repetitive tasks**: Deployments, backups, scaling
- **Critical procedures**: Incident response, disaster recovery
- **Error-prone operations**: Database migrations, certificate renewal
- **On-call procedures**: Alert triage, escalation paths
---
## Structure (2025 Standards)
### Required Sections
1. **Metadata**: Owner, risk level, last updated, approval
2. **Scope**: When to use, expected outcome
3. **Prerequisites**: Access, tools, system state
4. **Pre-Flight Checks**: Validate before execution
5. **Step-by-Step**: Numbered, copy-paste commands
6. **Verification**: Success criteria, monitoring
7. **Rollback**: When and how to revert
8. **Troubleshooting**: Common errors, escalation
### Risk Matrix
| Risk | Approval | Testing | Rollback |
|------|----------|---------|----------|
| Low | Self-service | Dev | Optional |
| Medium | Team lead | Staging | Recommended |
| High | Director | Full staging | Required |
| Critical | VP + Board | Prod-like | Mandatory |
---
## Best Practices
### Clarity
- ✅ Every step starts with action verb
- ✅ Commands copy-pasteable
- ✅ Expected output shown
- ✅ No assumptions about knowledge
### Safety
- ✅ Pre-flight checks prevent disasters
- ✅ Rollback tested and documented
- ✅ High-risk has approval gates
- ✅ Idempotent operations (safe to re-run)
### Automation
- ✅ Repetitive steps scripted
- ✅ Scripts version controlled
- ✅ Manual fallback documented
- ✅ Automation reduces MTTR
### Governance
- ✅ Owner assigned
- ✅ Quarterly review schedule
- ✅ Version controlled
- ✅ Change log maintained
---
## Automation Integration
```bash
# Script with safety checks
./scripts/deploy.sh production --dry-run # Preview
./scripts/deploy.sh production --execute # Execute
# Expected output:
# ✓ Pre-flight checks passed
# ✓ Deployment successful
# ✓ Verification passed
```
---
## Monitoring
### Dashboard Links
```markdown
## Monitor During Execution
- Error Rate: {dashboard_url}
- Latency: {dashboard_url}
- Throughput: {dashboard_url}
## Rollback Triggers
- Error rate > 5%
- P95 latency > 500ms for 5min
- Database connections exhausted
```
---
## Success Criteria
✅ Executable by any authorized engineer
✅ All commands tested in non-prod
✅ Rollback tested and working
✅ Execution time ±20% accurate
✅ Verification clearly defines success
**Effective runbooks minimize MTTR and reduce operational risk.**
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |