Update to Generate Runbook

{
  "description": "Create, review, validate, dry-run, and audit operational runbooks for software releases, incidents, migrations, recurring procedures, and other high-consequence workflows. Use when a user asks for a runbook, playbook, standard operating procedure, launch checklist, rollback plan, incident procedure, operational handoff, or validation of an existing runbook.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 218
    },
    {
      "relative_path": "assets/execution-record-template.md",
      "size_in_bytes": 3455
    },
    {
      "relative_path": "assets/runbook-template.md",
      "size_in_bytes": 2235
    },
    {
      "relative_path": "references/claude-adapter.md",
      "size_in_bytes": 550
    },
    {
      "relative_path": "references/codex-adapter.md",
      "size_in_bytes": 562
    },
    {
      "relative_path": "references/execution-and-evidence.md",
      "size_in_bytes": 5738
    },
    {
      "relative_path": "references/repository-targeting.md",
      "size_in_bytes": 2967
    },
    {
      "relative_path": "references/runbook-schema.md",
      "size_in_bytes": 3998
    },
    {
      "relative_path": "references/safety-gates.md",
      "size_in_bytes": 2404
    },
    {
      "relative_path": "scripts/check_runbook_drift.py",
      "size_in_bytes": 1204
    },
    {
      "relative_path": "scripts/inspect_repository_target.py",
      "size_in_bytes": 5592
    },
    {
      "relative_path": "scripts/install_skill.py",
      "size_in_bytes": 2097
    },
    {
      "relative_path": "scripts/test_skill.py",
      "size_in_bytes": 16428
    },
    {
      "relative_path": "scripts/validate_runbook.py",
      "size_in_bytes": 8501
    }
  ],
  "name": "generate-runbook",
  "skill_md_contents": "---\nname: generate-runbook\ndescription: Create, review, validate, dry-run, and audit operational runbooks for software releases, incidents, migrations, recurring procedures, and other high-consequence workflows. Use when a user asks for a runbook, playbook, standard operating procedure, launch checklist, rollback plan, incident procedure, operational handoff, or validation of an existing runbook.\n---\n\n# Generate Runbook\n\nTurn operational intent into a procedure another operator or agent can execute safely.\n\n## Workflow\n\n1. When using repository evidence, resolve and verify the intended target before inspection. Read `references/repository-targeting.md` and treat a required repository, branch, commit, cleanliness, or freshness mismatch as a stop condition unless the user explicitly accepts it. For supplied artifacts or non-repository operations, record their identity and limits without inventing a checkout or claiming live verification.\n2. Inspect the verified repository, system, existing documentation, and available tools before drafting.\n3. Separate verified facts from assumptions. Resolve safe, read-only questions directly.\n4. Identify the operator, environment, scope, prerequisites, expected duration, and completion signal.\n5. Classify each action:\n   - `read-only`: inspection with no state change\n   - `reversible`: state change with a tested recovery path\n   - `destructive`: deletion, replacement, irreversible migration, credential rotation, or broad external impact\n6. Add explicit approval gates before destructive actions and material external changes.\n7. Write the runbook using `assets/runbook-template.md`.\n8. Include exact verification after every consequential phase, not only at the end.\n9. Include rollback criteria and instructions that do not depend on the failed component.\n10. Validate drafts with `scripts/validate_runbook.py --mode draft`. Before execution, run `--mode ready` and independently verify live prerequisites, evidence and authorization.\n11. For execution or handoff, maintain `assets/execution-record-template.md`: current state, consumed authorizations, step outcomes and evidence bound to the exact artifact.\n12. Report the verified target identity, unresolved assumptions, validation results, and the next authorized action.\n\n## Operating modes\n\n- **Generate**: Create a new runbook from evidence and stated intent.\n- **Review**: Find ambiguity, unsafe steps, missing verification, and weak rollback coverage.\n- **Dry run**: Simulate decisions and commands without changing state. Never claim execution occurred.\n- **Execute / Resume**: Reconcile the durable execution record with live state, then follow the next authorized incomplete step. Preserve completed work and consumed grants; reconcile unknown outcomes before retrying.\n- **Drift audit**: Compare a runbook with current code, infrastructure, interfaces, and ownership.\n\nRead `references/runbook-schema.md` before generating or reviewing a runbook.\nRead `references/repository-targeting.md` before using repository evidence.\nRead `references/safety-gates.md` for production, destructive, security-sensitive, or external-facing operations.\nRead only the relevant platform adapter: `references/codex-adapter.md` or `references/claude-adapter.md`.\nRead `references/execution-and-evidence.md` for execution, resumption, handoff, or review of prior results. It defines authorization reuse, uncertain outcomes and the evidence needed to support a claim.\n\n## Required qualities\n\n- Make steps atomic, ordered, observable, and attributable.\n- Require an observable entry signal with an exact check, a rollback/containment trigger, and an explicit final go/no-go owner. Verify applicability and decision authority before reuse.\n- Use exact commands only after verifying paths, flags, environment, and scope.\n- Never put secrets, tokens, private content, or reviewer credentials in the runbook.\n- Prefer stable identifiers over UI position or screenshots.\n- State what must remain unchanged.\n- Define stop conditions for privacy leaks, data loss, security incidents, outages, and destructive recovery.\n- Keep evidence sanitized and proportionate.\n- Distinguish rollback from retry.\n- Do not invent commands, dashboards, owners, URLs, or success criteria.\n\n## Validation\n\nRun:\n\n```bash\npython3 scripts/validate_runbook.py PATH_TO_RUNBOOK.md --mode draft\npython3 scripts/validate_runbook.py PATH_TO_RUNBOOK.md --mode ready\n```\n\nTreat errors as blocking. Treat warnings as items requiring an explicit disposition.\nDraft mode allows incomplete fields with warnings. Ready mode requires the bundled\nMarkdown format, populated operational fields, stable step IDs, verification,\nfailure handling, approval disposition and retry safety. Update older runbooks to\nthe template before using ready mode. Execution records are reviewed by the\noperator; the linter does not parse or validate their ledgers.\n\nA structural pass is not authorization or proof of command safety, evidence\nvalidity, current system state or operational readiness. Check these separately.\n\nFor drift checks, run:\n\n```bash\npython3 scripts/check_runbook_drift.py PATH_TO_RUNBOOK.md REPOSITORY_ROOT\n```\n\nThis is a heuristic check. Confirm reported paths and commands manually before execution.\n"
}