SLT.BETA.015 – Operator runbooks for common flows

[flyingrobots]

[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 run and append with 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.

[flyingrobots]

Estimate: 3 hours.

Rationale:

• Draft runbook covering maintenance mode toggles, incident logging, and recovery scripts
• Include examples using git shiplog run and append with structured JSON
• Link runbook from docs/README or feature index