katashiro-guided-runbook

katashiro-guided-runbook

The operator executes; you navigate. You write the runbook as a canvas, keep the next command marked, read the output they paste, compare it with what the step expects, and log every step in the canvas. You never run a command that changes a system — not even "just this once".

Uses katashiro-point-at (§3–4, canvas pointing) and katashiro-ask-user (cards). Install both.

Requirements

• The current chat is a Katashiro chat, so katashiro.canvas_* and katashiro.ask_user are available. Not in Discord/Slack threads or cron turns.
• Pointing (canvas_highlight, canvas_inject_css) works only while your conversation is the one on screen. From a background conversation they are refused: keep logging, point again when the user is back.

1. Draft the runbook canvas

katashiro.canvas_open a markdown canvas with this shape:

# <Goal> — runbook
Ticket: <link> · Owner: <operator> · Order: stg → prd-a → prd-b · Timezone: <operator's, e.g. TPE>
Rollback summary: <one or two lines>

## Prerequisites
### pre · 1 · <tools / access check>
...

## stg
### stg · 1 · <short name>
Command:
```sql
SELECT ...
```
Expected: <counts, %, states the output must show>
Stop if: <the condition that halts the run>

### stg · 2 · ⚠️ DESTRUCTIVE · <short name>
...
Rollback (stg): <commands>

## prd-a
...

## Execution log
| Time (TPE) | Env | Step | Before → after | Verdict | Notes |
|---|---|---|---|---|---|
| — | — | — | — | — | end of log |

• Every step gets its own heading, unique in the whole canvas (### <env> · <n> · <name>). The same command often runs in every environment; canvas_highlight's find must match exactly one block, so always point with heading.
• One command per code block, copy-pasteable. Mark destructive steps ⚠️ DESTRUCTIVE in the heading.
• A read-only helper you may run yourself (a SELECT through a tool you have) is labelled (read-only, agent may run) in its heading. Anything else, the operator runs.
• The execution log is the last section, and its last row is the fixed anchor | — | — | — | — | — | end of log |. New rows go just above it, so the lines of every step above never move (§2 relies on that).
• Commands read secrets from the operator's environment or vault ($CH_PASSWORD, vault read …). Never put a key, a password, a real IP list or other sensitive identifier in the canvas or chat.