runbook

Runbook Generation Skill

Trigger

• Keywords: runbook, release runbook, deployment handbook, release handbook, operational guide, pre-release checklist, rollback plan

When NOT to Use

Scenario	Alternative
Incident response runbook	v2 (not yet implemented)
Code review	/codex-review-fast
Architecture design	/architecture
Tech spec writing	/tech-spec
Request tracking	/create-request

Usage

/runbook                              # Auto-detect feature, create or update
/runbook <feature-keyword>            # Specify feature
/runbook --update                     # Force update mode
/runbook --check                      # Read-only staleness validation
/runbook --request <path|title>       # Specify target request (multi-request features)

Workflow

sequenceDiagram
    participant U as User
    participant S as /runbook
    participant FR as Feature Resolver
    participant CB as Codebase
    participant RB as runbook-release.md

    U->>S: /runbook [feature] [--update|--check] [--request path]
    S->>FR: node scripts/resolve-feature.js
    FR-->>S: {key, doc_inventory, source sets}
    S->>S: Mode dispatch + Request selection

    alt Create Mode
        S->>CB: Read current_authority + requests/*.md
        S->>CB: Scoped discovery (5-priority cascade)
        S->>RB: Write runbook-release.md from template
    else Update Mode
        S->>RB: Read existing runbook + provenance
        S->>CB: Compare current state vs provenance SHAs
        S->>RB: Edit changed sections only
    else Check Mode
        S->>RB: Read existing runbook + provenance
        S->>CB: Validate per-section SHAs
        S-->>U: Report: Fresh/Stale/Missing/Unknown
    end

Phase 0: Context Resolution

Resolve feature using the 5-level cascade:

The wrapper, not the CLI directly: resolve-feature.js owns the failure payload, so the full shape with scan_error: true arrives however the CLI fails — a nonzero exit, a signal, a partial write, a payload that is not the agreed shape. (It cannot survive node itself being unavailable: nothing running under node can. What it removes is the CLI's failure domain, not the interpreter's.) Calling the CLI with || echo '{}' produces a payload the gate below cannot recognise as a failure.