SLT.BETA.015 – Operator runbooks for common flows #77
Description
[SLT.BETA.015] Operator runbooks for common flows
Overview
Create operator runbooks that document how to use Shiplog for maintenance windows, incident response, and trust rotations using the new command wrappers.
References & Assets
- Figma / Design: N/A
- Product Spec: N/A
- Related Issues / PRs: docs/features/command-reference.md
- Feature Flags / Experiments: N/A
- Other Assets: N/A
User Story
As an operations responder, I want ready-to-use runbooks that leverage Shiplog commands, so that I can execute maintenance and incident tasks consistently.
Acceptance Criteria
- Runbook pages cover maintenance mode flows, incident timelines, and trust rotations
- Examples include
git shiplog runandappendwith structured JSON - Runbooks linked from docs index/README
- Content reviewed by operations stakeholders
Definition of Done
Runbooks published with actionable steps and examples, linked throughout docs.
Scope
In-Scope
- Authoring new runbook pages under docs/runbooks
- Linking runbooks from relevant docs
Out-of-Scope
- Automating runbook execution
- Video tutorials or webinars
Deliverables
- Est. Lines of Code: ~150 (docs)
- Est. Blast Radius: docs/runbooks, README references
Implementation Details
High-Level Approach
Draft runbooks for each scenario, include copy/paste commands, embed JSON examples, and ensure cross-links from command reference.
Affected Areas
- docs/runbooks/*.md
- docs/README.md
- README.md
Implementation Steps
- Outline key operator scenarios and owners
- Draft runbooks with step-by-step instructions
- Add Shiplog command examples with context
- Cross-link runbooks from docs index/README
- Review with ops stakeholders
Test Plan
Happy Path
- Docs build passes and runbooks render correctly
Edge Cases
- Embedded command snippets validated for accuracy
Failure Cases
- N/A (documentation)
Monitoring & Success Metrics
- Runbook usage tracked via docs analytics (future nice-to-have)
QA Sign-off Matrix
| Environment | Surface | Owner | Status | Notes |
|---|---|---|---|---|
| Docs build | Markdown | TBD | Pending | Validate via markdownlint |
Requirements
Hard Requirements
- Runbooks must provide actionable, copy/paste-ready steps
Soft Requirements
- Include JSON examples for structured logging
Runtime Requirements
- N/A
Dependencies & Approvals
- Ops lead review
Production Notes
Priority: 3 / 5
Improves operator experience (P2).
Complexity: 2 / 5
Documentation effort with coordination.
Estimate: 8 - 12 hours
Includes drafting, review, revisions.
Risk & Rollback
- Primary Risks: Out-of-date instructions
- Mitigations: Note version assumptions; plan periodic review
- Rollback / Kill Switch: Revert doc changes if inaccurate
Additional Notes
Incorporate feedback from DX notes requesting concise runbooks.