/runbook

name: runbook
description: "Generate and update feature release runbooks from existing docs and codebase. Use when: creating operational runbook, release handbook, deployment checklist, pre-release preparation. Not for: incident response (v2), code review (use codex-code-review), architecture design (use architecture)."
allowed-tools: Read, Grep, Glob, Bash(git:*), Bash(node:*), Write, Edit, Agent, AskUserQuestion

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.

**Decide the branch yourself, then run one command.** This skill grants `Bash(node:*)`, which matches a direct `node …` invocation and nothing else — a shell `if`/`[ … ]`/`$(…)` compound is not a `node` command and cannot run here. Parse `$ARGUMENTS` first (Step 1 below), then issue exactly one of:

node scripts/resolve-feature.js --feature <the feature key from $ARGUMENTS>

node scripts/resolve-feature.js

Use the first when `$ARGUMENTS` carried a positional feature key, the second otherwise. Pass the key as a separate argv token — never interpolate it into a larger shell expression.

| Source | Mapping | |--------|---------| | `/runbook auth` | Positional key `auth` → `--feature auth` (two separate argv tokens) | | `/runbook` (no arg) | No `--feature`, resolver uses branch/diff/fallback | | `/runbook --check` | No `--feature`, parse flags only |

| Step | Action | |------|--------| | 1 | Parse `$ARGUMENTS` for feature key or `--check`/`--update`/`--request` flags | | 2 | Run feature resolver, get `key`, `doc_inventory`, and the four source sets (`current_authority`, `design_records`, `work_records`, `history_records`) | | 2b | **If `scan_error !== false`, stop** — not `=== true`: a payload missing the field is a failure too. See the gate below | | 3 | Check for `runbook-release.md` specifically in feature directory (not any `runbook-*.md`) | | 4 | Determine mode: create (`runbook-release.md` absent) / update (`runbook-release.md` exists) / check (`--check` flag) |

> **`scan_error` gate.** Gate on **`scan_error !== false`**, not on `scan_error === true`. When it > is not exactly `false` the four source sets are **unknown, not empty** — the corpus could not be > enumerated (unreadable directory, broken taxonomy, no repository), *or* the resolver never ran > and a shell fallback supplied a payload with no such field at all. `{}` is the shape that made > the stricter test useless: it has no `scan_error`, so `=== true` is false and the gate passes a > payload that contains nothing. Do not proceed as though the feature has no authority documents — > report and take the ⚠️ Need Human exit. A `key` may still be present, so a non-null `key` is not > evidence the sets are complete.

**Note**: Mode dispatch keys off the specific file `runbook-release.md`, not any runbook-typed doc in `doc_inventory`. A feature may have `runbook-deploy.md` (a different topic) without triggering update mode for the release runbook.

Request Selection

| Condition | Behavior | |-----------|----------| | `--request` specified | Use specified request | | Single active request | Auto-select | | Multiple active requests | AskUserQuestion: list requests, let user choose | | No active requests | Use most recent request (warn) |

Phase 1: Content Discovery (Create/Update modes)

Use **scoped discovery cascade** — narrow to wide, with confidence degradation:

| Priority | Scope | Confidence | |----------|-------|------------| | 1 | Request `Related Files` paths | High | | 2 | `current_authority` — code, `rules/`, and the docs that claim to be current | High | | 3 | `design_records` (tech spec, architecture) | Medium — *intent only*, mark steps unverified | | 4 | Fe