social-app/docs/plans/2026-02-25-runtime-runbook-optimization-implementation-plan.md

Runtime Runbook Optimization Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: 将 docs/runtime/runtime-runbook.md 重构为面向运维的可执行手册，覆盖门禁、启动、验证、故障与回滚全流程。

Architecture: 保持单文档模式，在不改变脚本和运行时代码的前提下重排章节与命令。先做命令基线校对，再做文档结构重构，最后执行可达性验证并提交。所有命令以仓库现有脚本和 compose 路径为准。

Tech Stack: Markdown, Bash, Docker Compose, tmux, uv。

---

Task 1: 命令与脚本基线核对

Files:

• Modify: docs/runtime/runtime-runbook.md
• Verify: infra/scripts/app-up.sh

Step 1: 写失败校验（当前 runbook 存在 TODO 与历史表述）

grep -n "TODO\|dev-app-up" docs/runtime/runtime-runbook.md

Step 2: 运行并确认失败

Run: grep -n "TODO\|dev-app-up" docs/runtime/runtime-runbook.md
Expected: 命中至少 1 条（表示需重构）。

Step 3: 写最小实现（命令映射清单）

- 启动脚本统一为 infra/scripts/app-up.sh
- bootstrap 命令统一为 docker compose --env-file .env -f infra/docker/docker-compose.yml ...
- 迁移/初始化强调 init-job --build

Step 4: 运行验证

Run: bash -n infra/scripts/app-up.sh
Expected: exit 0。

Task 2: 文档结构重构为运维分层

Files:

• Modify: docs/runtime/runtime-runbook.md

Step 1: 写失败校验（缺失目标章节）

grep -n "Bootstrap Gate\|Operational Verification\|Incident Playbook\|Rollback" docs/runtime/runtime-runbook.md

Step 2: 运行并确认失败

Run: grep -n "Bootstrap Gate\|Operational Verification\|Incident Playbook\|Rollback" docs/runtime/runtime-runbook.md
Expected: 命中不完整或为空。

Step 3: 写最小实现（章节重排）

1. Scope & Preconditions
2. Bootstrap Gate (Mandatory)
3. Service Start/Stop
4. Operational Verification (L1/L2/L3)
5. Incident Playbook
6. Rollback Procedure

Step 4: 运行验证

Run: grep -n "Bootstrap Gate\|Operational Verification\|Incident Playbook\|Rollback Procedure" docs/runtime/runtime-runbook.md
Expected: 4 个目标章节都能命中。

Task 3: 补齐运维验证与故障处理细则

Files:

• Modify: docs/runtime/runtime-runbook.md

Step 1: 写失败校验（缺少通过判定）

grep -n "通过标准\|判定" docs/runtime/runtime-runbook.md

Step 2: 运行并确认失败

Run: grep -n "通过标准\|判定" docs/runtime/runtime-runbook.md
Expected: 命中不足。

Step 3: 写最小实现（每段加判定）

- L1 必跑：health/compose/smoke + 通过标准
- L2 可选：auth/profile + 通过标准
- L3 可选：agent_chat tests + 通过标准
- 故障条目：症状/定位/修复

Step 4: 运行验证

Run: grep -n "L1 必跑\|L2 可选\|L3 可选\|通过标准" docs/runtime/runtime-runbook.md
Expected: 关键段落均命中。

Task 4: 收尾校验与提交

Files:

• Modify: docs/runtime/runtime-runbook.md

Step 1: 运行文档语义检查（关键命令可达）

bash -n infra/scripts/app-up.sh
PYTHONPATH=backend/src uv run python -c "import core.runtime.cli"

Step 2: 运行并确认通过

Run: bash -n infra/scripts/app-up.sh
Expected: exit 0。

Run: PYTHONPATH=backend/src uv run python -c "import core.runtime.cli"
Expected: 无报错并 exit 0。

Step 3: 提交

git add docs/runtime/runtime-runbook.md \
  docs/plans/2026-02-25-runtime-runbook-optimization-design.md \
  docs/plans/2026-02-25-runtime-runbook-optimization-implementation-plan.md
git commit -m "docs(runtime): optimize runbook for ops workflow"