p24-infra Docs

playbook-lifecycle

6 min read

Playbook Lifecycle — Writing, Modifying, and Missing Playbooks

Situation 1 — No playbook exists yet (uncharted territory)

Rule: If you’re about to do something significant and there’s no playbook, write the playbook FIRST in a draft form, then execute.

Steps

  1. Check docs/playbooks/ for a related playbook — maybe it exists under a different name.

    Get-ChildItem C:\code_2026\p24-infra\docs\playbooks\ -Filter "*.md" | Select-Object Name

  2. If none exists — create a draft playbook before starting the operation:

    • File name: docs/playbooks/<topic-slug>.md
    • Use the template below
    • Mark it Status: DRAFT at the top
    • Write what you know: trigger, pre-conditions, intended steps
    • Leave unknowns as TODO: verify — don’t stall

  3. Execute the operation, updating the draft in real time as you learn:

    • What worked (confirm steps)
    • What failed (add known-bad approaches under “Common mistakes”)
    • Exact commands with real output samples

  4. After successful execution, promote to Status: STABLE and commit the playbook in the same PR as the feature/fix.

Why draft-first matters

Writing the playbook before executing forces you to articulate what you’re about to do and why — this is the same mechanism that catches the “deploy to vps-i1 when only bms-4 is active” class of errors. If you can’t write even a draft, you don’t understand the operation well enough to execute it.

Situation 2 — Playbook exists but is wrong or incomplete

Rule: Fix the playbook BEFORE (or as part of) the operation, not after. A wrong playbook is worse than no playbook — it creates false confidence.

When to update

  • You discover a step that doesn’t work or has a better alternative
  • A server role changed (e.g., vps-i1 was disabled as worker host)
  • A tool was replaced (e.g., Infisical → SOPS)
  • A mistake happened because the playbook was silent on an edge case

Steps

  1. Read the existing playbook to understand current state.
  2. Create a branch: git checkout -b fix/playbook-<topic> origin/main
  3. Edit the playbook — be specific:
    • Add a ## Known issues section if correcting a factual error
    • Add a datestamp comment: <!-- updated 2026-XX-XX: <reason> -->
    • If the entire approach changed, mark old sections with ~~strikethrough~~ and add a “Superseded approach” heading rather than deleting — history helps future debugging
  4. Commit and open a PR targeting main.

What NOT to do

  • Do not edit the playbook after the fact as a post-mortem cleanup — fix it BEFORE or DURING
  • Do not leave the wrong playbook in place “to fix later” — it will mislead the next session
  • Do not create a new playbook when updating an existing one would suffice (causes duplicates)

Situation 3 — Operation conflicts with playbook

This is the highest-risk case. Examples:

  • Playbook says “deploy to bms-4” but you’re about to deploy to vps-i1
  • Playbook says “service is PROTECTED, no new agents” but you’re configuring an agent

Rule: The playbook wins. Stop. Re-read it. Post a question before proceeding.

If you believe the playbook is wrong (e.g., server roles changed):

  1. Update the playbook first (Situation 2 above)
  2. Get the PR merged or at minimum committed to your branch
  3. Then execute the operation following the updated playbook

Never execute an operation that contradicts an unmodified playbook.

Situation 4 — Cannot execute according to any playbook (escalate to human-action)

When: you’ve read the relevant playbook, the playbook is correct, but you genuinely cannot complete the operation — missing credentials, destructive step with no rollback path, ambiguous decision that affects shared infrastructure, or the situation is outside any existing playbook’s scope.

Rule: Do NOT improvise. Present options to the user, wait for their decision.

Escalation format — interactive session (user present in conversation)

Stop and present this exact structure in conversation:

Nie mogę kontynuować: [konkretna operacja — co, na którym serwerze]
Powód: [dokładna przyczyna blokady]
Playbook: docs/playbooks/<name>.md

1. [Opis co zrobię — konkretna akcja, nie abstract]
2. [Opis co zrobię — inna konkretna akcja]
3. [Opis co zrobię — np. pomiń ten krok i kontynuuję resztę]
4. Opisz co chcesz żebym zrobił

Sugeruję: <cyfra>

Rules for the options list:

  • Options 1–3 are concrete actions Claude will take immediately after the user replies with that digit
  • Option 4 is always “user describes” — never remove it
  • The recommended option is the one with lowest risk / most reversible
  • Never present more than 4 options (cognitive overload)
  • Label which option is suggested (Sugeruję: N) — one recommendation, no hedging

Example:

Nie mogę kontynuować: deploy spawn-worker.sh na vps-i1
Powód: worker-queue-operations.md mówi że vps-i1 ma enabled=false — nie jest aktywnym workerem
Playbook: docs/playbooks/worker-queue-operations.md

1. [Zalecane] Deploy tylko na bms-4 (54.36.123.110) zgodnie z playbootem
2. Utwórzę issue #human-action i zatrzymuję się — wróćmy gdy bms-4 jest potwierdzone
3. Pomiń deploy, kontynuuję pozostałe taski które nie zależą od tego kroku
4. Opisz co chcesz żebym zrobił

Sugeruję: 1

Escalation format — autonomous worker (headless, no user in conversation)

Worker nie może pytać — tworzy GH issue natychmiast:

gh issue create --repo radieu/p24-infra `
  --title "[Human Action] <what needs deciding>" `
  --label "human-action,bug" `
  --body @"
## Nie mogę kontynuować
 
**Operacja:** <co, na którym serwerze>
**Powód:** <dokładna przyczyna>
**Playbook:** docs/playbooks/<name>.md
 
## Opcje do rozważenia
 
1. <opcja 1 — konkretna akcja>
2. <opcja 2>
3. <opcja 3>
 
## Stan częściowy
 
<co zostało zrobione, co nie — partial state is dangerous>
 
## Jak wznowić
 
<dokładne kroki do wklejenia po podjęciu decyzji>
"@

Następnie: link do oryginalnego issue + stop. Kontynuuj inne taski niezależne od tego kroku.

Escalation label routing

ScenarioLabels
Missing credential / accesshuman-action, security
Destructive action with no rollbackhuman-action, P1
Server role ambiguityhuman-action, infrastructure
Decision affecting shared infrastructurehuman-action, infrastructure
Infra element broken / unavailablehuman-action, bug

What NOT to do

  • Do NOT silently use vps-i1 when playbook says bms-4 is disabled — that’s an improvisation
  • Do NOT present abstract options (“should I do X or Y?”) — only concrete actions Claude will take
  • Do NOT skip the GH issue for workers — the issue is the only escalation channel when headless
  • Do NOT present more than 4 options — pick the best 3, let option 4 be open

Playbook template

# <Topic> — Playbook
 
<!-- Status: DRAFT | STABLE | DEPRECATED -->
Status: DRAFT
 
## What triggers this
 
<When would someone need to read this playbook? What event or task requires these steps?>
 
## Pre-conditions
 
- [ ] <What must be true before starting>
- [ ] <What access/credentials are needed>
 
## Steps
 
1. <Step 1>
   ```bash
   <exact command>

Expected output: <what success looks like>

  1. <Step 2>

Verification

<How do you confirm the operation succeeded? Commands + expected output.>

Rollback

Common mistakes

  • : 

---

## Playbook index maintenance

After writing or significantly updating a playbook, check if `.claude/task-playbooks/server-operation.md`
(or the relevant task-playbook) still has accurate pointers. Update the table if needed.

The task detection table in `CLAUDE.md` maps task keywords → task-playbooks; task-playbooks map operations → `docs/playbooks/`. Both ends of this chain must be up to date.

Graph View

Backlinks