@colin4k1024/tsp 2.4.1 → 2.4.2

package/docs/runbooks/artifact-persistence.md

@@ -0,0 +1,257 @@
+# Artifact Persistence Convention
+
+## 用途
+
+定义 `/team-*` 命令产出物的持久化存储规则，确保 PRD、Delivery Plan、架构设计、执行日志、Deployment Context、Launch Acceptance、Release Plan、Closeout Summary、Handoff 记录、ADR 以及系统记忆可被审计和回溯。
+
+---
+
+## 目录结构（消费方项目仓库）
+
+```text
+docs/
+  artifacts/
+    INDEX.md                                 # 所有任务的汇总索引（追加更新）
+    {YYYY-MM-DD}-{slug}/
+      prd.md                                 # /team-intake 产出
+      delivery-plan.md                       # /team-plan 产出
+      arch-design.md                         # /team-plan，architect 角色产出（必填）
+      api-contract.md                        # architect / backend-engineer 产出（可选）
+      execute-log.md                         # /team-execute 产出（必填）
+      test-plan.md                           # /team-review 产出
+      launch-acceptance.md                   # /team-review 产出（上线准入结论）
+      deployment-context.md                  # /team-release 产出（环境/配置/回滚真相源）
+      release-plan.md                        # /team-release 产出
+      closeout-summary.md                    # /team-closeout 产出
+      handoffs/
+        {NNN}-{from-role}-to-{to-role}.md    # /handoff 产出，NNN 序号自增
+  adr/
+    ADR-001-{title}.md                       # ADR（全局序号，独立于任务目录）
+    ADR-002-{title}.md
+  memory/                                    # 系统记忆（跨任务持久化，不属于单个任务）
+    project-context.md                       # 项目级上下文快照（覆盖更新）
+    backlog.md                               # 跨任务 backlog 真相源（持续更新）
+    decisions.md                             # 轻量决策日志（追加）
+    lessons-learned.md                       # 经验沉淀（追加）
+    sessions/
+      {YYYY-MM-DD}-{NNN}-{slug}.md           # 每次命令链路的会话摘要（NNN 序号自增）
+```
+
+> 如果上述目录不存在，agent 在写入前先创建。
+
+---
+
+## Slug 生成规则
+
+1. 取需求标题或任务名称。
+2. 转为小写，中文转拼音首字母或保留核心英文语义词。
+3. 空格和特殊字符替换为 `-`，连续 `-` 合并。
+4. 截断至 30 字符以内。
+5. 示例：`用户登录流程改造` -> `user-login-flow`；`Payment Retry Logic` -> `payment-retry-logic`。
+
+---
+
+## Frontmatter 规范
+
+每个 artifact 文件开头必须包含：
+
+```markdown
+---
+artifact: prd | delivery-plan | arch-design | api-contract | execute-log | test-plan | launch-acceptance | deployment-context | release-plan | closeout-summary | backlog-snapshot | handoff | adr | project-context | decision | lesson | session-summary
+task: {slug}
+date: {YYYY-MM-DD}
+role: {产出角色，如 tech-lead / architect / qa-engineer / devops-engineer}
+status: draft | approved
+---
+```
+
+---
+
+## ADR 编号规则
+
+1. 扫描 `docs/adr/` 目录，找出现有文件中最大的三位序号。
+2. 新 ADR 编号 = 最大值 + 1，左补零至三位。
+3. 若目录为空，从 `ADR-001` 开始。
+4. 文件命名：`ADR-{NNN}-{slug}.md`，slug 规则同上。
+
+---
+
+## INDEX.md 格式
+
+### 初始化（首次创建）
+
+```markdown
+# Artifacts Index
+
+| 日期 | 任务 | PRD | Delivery Plan | Arch Design | Test Plan | Launch Acceptance | Deployment Context | Release Plan | Closeout | ADR | 状态 |
+|------|------|-----|---------------|-------------|-----------|-------------------|--------------------|--------------|----------|-----|------|
+```
+
+### 追加新任务行
+
+每次 `/team-intake` 创建新任务时追加一行：
+
+```text
+| {YYYY-MM-DD} | {slug} | prd.md 链接 | - | - | - | - | - | - | - | - | intake |
+```
+
+实际写入时将占位符替换为真实日期、slug，并生成相对路径链接。
+
+后续各阶段完成后，更新对应列为链接，并将状态列更新为 `plan` / `execute` / `review` / `accepted` / `released` / `closed`。
+
+---
+
+## Handoff 序号规则
+
+1. 扫描 `docs/artifacts/{slug}/handoffs/` 目录，找出现有文件最大的三位序号。
+2. 新文件序号 = 最大值 + 1，左补零至三位。
+3. 若目录为空，从 `001` 开始。
+4. 文件命名：`{NNN}-{from-role}-to-{to-role}.md`。
+
+---
+
+## 架构设计文档（arch-design.md）规范
+
+由 `architect` 角色在 `/team-plan` 阶段产出，至少包含：
+
+- **系统边界**：外部依赖、集成点、边界内外划分。
+- **组件拆分**：主要模块 / 服务及其职责。
+- **关键数据流**：核心路径的数据流转，可用 Mermaid 图。
+- **接口约定**：主要 API 入口、协议、认证方式。
+- **技术选型**：关键语言、框架、中间件选择及原因。
+- **风险与约束**：已知技术风险和上线前必须解决的约束。
+
+---
+
+## 执行日志（execute-log.md）规范
+
+由研发角色在 `/team-execute` 阶段产出，记录实际执行过程：
+
+- **计划 vs 实际**：原计划完成哪些，实际完成哪些，偏差原因。
+- **关键决定**：实施过程中做出的技术决定。
+- **阻塞与解决**：遇到的阻塞、根因和最终解决方式。
+- **影响面**：涉及的模块、接口、数据库、配置。
+- **未完成项**：因范围或时间调整而延后的内容。
+
+---
+
+## 上线验收（launch-acceptance.md）规范
+
+由 `qa-engineer` 主责，在 `/team-review` 阶段产出，用于记录“是否允许上线”的正式结论：
+
+- **验收范围**：本次实际验收的业务、技术和非功能边界。
+- **验收证据**：关联 `test-plan.md`、关键测试结果、关键环境和 artifact。
+- **已满足项**：已经满足的功能、数据、回滚、监控与运维要求。
+- **接受风险**：当前未满足但接受上线的风险、原因与缓解措施。
+- **阻塞项**：仍然阻塞上线的问题与 owner。
+- **上线结论**：允许上线 / 有条件允许上线 / 不允许上线。
+
+---
+
+## 部署上下文（deployment-context.md）规范
+
+由 `devops-engineer` 主责，在 `/team-release` 阶段产出，作为上线所需环境与操作上下文的真相源：
+
+- **环境清单**：环境用途、访问入口、部署目标。
+- **部署入口**：主入口、手工入口、回退入口、前置条件。
+- **配置与密钥**：环境变量、配置项、密钥来源、轮换与访问方式。
+- **运行保障**：feature flag、灰度控制、监控、告警、值守与观察窗口。
+- **回滚与恢复**：触发条件、回滚路径、验证回滚成功的方法。
+
+---
+
+## 收口总结（closeout-summary.md）规范
+
+由 `tech-lead` / `devops-engineer` 在 `/team-closeout` 阶段产出，用于记录发布后观察结果、最终状态判断和 backlog 回填情况：
+
+- **发布后观察结果**：实际发布时间、指标变化、告警或事故、用户反馈。
+- **目标达成情况**：原目标、实际结果、未达成部分、偏差原因。
+- **当前状态判断**：正式收口 / 部分收口 / 暂不收口，以及残余风险。
+- **遗留项**：需要补丁、后续任务或再次发布的事项。
+- **知识沉淀**：lessons learned、后续 owner、回看时间。
+- **Backlog 回填**：必须明确是否已同步到 `docs/memory/backlog.md`。
+
+---
+
+## 系统记忆（docs/memory/）规范
+
+系统记忆是跨任务、跨会话的持久化知识，不属于单个任务目录。
+
+### project-context.md
+
+- **覆盖更新**：每次 `/team-plan`、`/team-release` 或 `/team-closeout` 后刷新。
+- 内容：项目名称、tech stack、当前活跃任务 slug、当前阶段、关键依赖、团队角色、上次发布版本、未解决风险、下一步建议。
+
+### delivery-plan.md 补充约定
+
+- 若任务属于既有项目改造，`delivery-plan.md` 应包含 `Brownfield Context Snapshot` 章节。
+- 若任务需要进入 `/team-execute`，`delivery-plan.md` 应包含 `Story Slice Plan` 章节，用于表达可独立验收的执行单元。
+
+### backlog.md
+
+- **持续更新**：作为跨任务 backlog / roadmap 的真相源。
+- 推荐按 [../../templates/backlog-snapshot.md](../../templates/backlog-snapshot.md) 结构维护。
+- 至少承接四类信息：当前版本未完成项、发布后遗留项、技术债、下一阶段候选。
+- 每次 `/team-closeout` 后，如出现遗留项或下一阶段候选，必须更新。
+
+### decisions.md
+
+- **追加更新**：每次 `/team-execute` 或 `/team-review` 后，如有轻量决策则追加。
+- 每条格式：
+
+```text
+## {YYYY-MM-DD} {决策标题}
+- 背景：{一句话说明为什么要做这个决定}
+- 决策：{做了什么}
+- 影响：{影响哪些组件或流程}
+- 关联任务：{slug}
+```
+
+### lessons-learned.md
+
+- **追加更新**：每次 `/team-review`、`/team-release` 或 `/team-closeout` 后，如有经验教训则追加。
+- 每条格式：
+
+```text
+## {YYYY-MM-DD} {教训标题}
+- 场景：{什么情况下发生的}
+- 问题：{出了什么问题或值得记录的点}
+- 建议：{下次如何避免或复用}
+- 关联任务：{slug}
+```
+
+### sessions/{YYYY-MM-DD}-{NNN}-{slug}.md
+
+- **每次 `/team-closeout` 完成后**写入，代表一个完整交付链路的收口摘要。
+- 也可在 `/team-review` 或 `/team-release` 后写入中间状态会话摘要。
+- 内容：链路起止时间、完成的任务 slug、关键产出链接、遗留事项。
+
+---
+
+## 各命令写入职责
+
+| 命令 | 写入文件 | 同时更新 |
+|------|----------|----------|
+| `/team-intake` | `docs/artifacts/{slug}/prd.md` | `docs/artifacts/INDEX.md`（新增任务行） |
+| `/team-plan` | `docs/artifacts/{slug}/delivery-plan.md`、`arch-design.md` | `INDEX.md` Delivery Plan + Arch Design 列；若有 ADR 则写 `docs/adr/ADR-{NNN}.md`；刷新 `docs/memory/project-context.md` |
+| `/team-execute` | `docs/artifacts/{slug}/execute-log.md` | 若有新 ADR 则写 `docs/adr/`；若有轻量决策则追加 `docs/memory/decisions.md` |
+| `/team-review` | `docs/artifacts/{slug}/test-plan.md`、`launch-acceptance.md` | `INDEX.md` Test Plan + Launch Acceptance 列；若有经验教训则追加 `docs/memory/lessons-learned.md`；状态更新为 `review` 或 `accepted` |
+| `/team-release` | `docs/artifacts/{slug}/deployment-context.md`、`release-plan.md` | `INDEX.md` Deployment Context + Release Plan 列和状态列；刷新 `docs/memory/project-context.md`；若有经验教训则追加 `docs/memory/lessons-learned.md` |
+| `/team-closeout` | `docs/artifacts/{slug}/closeout-summary.md` | `INDEX.md` Closeout 列和状态列；刷新 `docs/memory/project-context.md`；按需更新 `docs/memory/backlog.md`、`docs/memory/lessons-learned.md`；写入 `docs/memory/sessions/` 会话摘要 |
+| `/handoff` | `docs/artifacts/{slug}/handoffs/{NNN}-{from}-to-{to}.md` | 无需更新 INDEX.md |
+
+---
+
+## 注意事项
+
+- **追加，不覆盖**：INDEX.md、decisions.md、lessons-learned.md 始终只追加，不删改已有行。
+- **覆盖更新**：`project-context.md` 保持为当前最新状态的单一真相源。
+- **slug 一致性**：同一个任务在所有命令中使用相同 slug，由 `/team-intake` 在首次运行时确定。
+- **ADR 全局序号**：ADR 序号跨任务累计，不在单个任务目录内重新计数。
+- **execute-log.md 必填**：不是可选摘要，团队依赖它追溯实施偏差和决定。
+- **arch-design.md 必填**：`/team-plan` 阶段必须输出。
+- **launch-acceptance.md 不是 test-plan 的替代品**：一个负责测试事实，一个负责上线准入结论。
+- **deployment-context.md 不是 release-plan 的附录**：环境、配置、密钥和回滚入口必须可独立检索。
+- **closeout-summary.md 不是 release-plan 尾注**：只有经过观察窗口并完成 backlog 回填，任务才算真正收口。
+- **backlog.md 是跨任务真相源**：发布后遗留项、技术债和二期候选必须进入 `docs/memory/backlog.md`。
+- **路径前缀**：所有路径均相对于消费方项目仓库根目录，不是 Team Skills Platform 本身。

package/docs/runbooks/backend-engineer-daily-operations.md

@@ -0,0 +1,63 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# Backend Engineer 日常操作手册
+
+本文面向后端工程师，说明在 Team Skills Platform 下，接口、权限、数据库和发布风险应如何在主链中表达。
+
+如果你想先看命令与能力总表，先读 [command-and-capability-matrix.md](command-and-capability-matrix.md)。
+
+## 1. 你的默认职责
+
+- 设计并实现接口和领域逻辑
+- 处理权限、错误码、分页和异常路径
+- 提供单测、集成测试或迁移脚本结果
+- 把兼容性和发布风险清楚交接出去
+
+## 2. 开始实现前必须确认什么
+
+- 接口契约是否已明确
+- 是否涉及数据库变更
+- 是否涉及 custom overlay，如 私有流程、权限集成
+- 是否需要 architect 或 devops-engineer 提前介入
+
+## 3. 实现时的固定检查
+
+- 兼容性
+- 错误处理
+- 权限边界
+- 性能与查询风险
+- 回滚可行性
+
+## 4. 进入 QA 前应交付什么
+
+- 代码变更摘要
+- 单测/集成测试结果
+- 接口兼容性说明
+- 数据迁移与回滚说明
+- 已知限制与剩余风险
+
+## 5. 常用命令组合
+
+- `/team-intake`：识别目标和 overlay 候选项
+- `/team-plan`：拆接口、数据和测试任务
+- `/tdd`：先锁接口边界、测试和回归口径
+- `/multi-backend`：做专项拆解
+- `/team-execute`：汇总实现与验证
+- `/code-review`：做实现质量审查
+- `/verify`：补关键路径和兼容性证据
+- `/handoff`：交给 QA 或 tech-lead
+
+## 6. 常见错误
+
+- 只交付代码，不交付兼容性说明
+- 数据库改了，但没有迁移和回滚方案
+- 明明适合先用 `/tdd` 锁定接口与测试边界，却直接写实现
+- custom overlay 已用到，却没有执行记录
+
+后端专项场景可继续看 [../../examples/springboot-service-CLAUDE.md](../../examples/springboot-service-CLAUDE.md)。

package/docs/runbooks/batch-optimization-completion-checklist.md

@@ -0,0 +1,104 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-29
+updated: 2026-03-29
+owner: 工程团队
+---
+
+# 本轮批量优化完成情况清单
+
+本文用于快速回答一个问题：这轮批量优化到底已经完成了什么。
+
+如果你想看减法判断依据，继续看 [../plans/llm-surface-reduction-audit.md](../plans/llm-surface-reduction-audit.md)。如果你想看逐阶段执行历史，继续看 [../plans/llm-surface-reduction-execution-history.md](../plans/llm-surface-reduction-execution-history.md)。
+
+## 1. 文档入口收敛
+
+### 1.1 已完成
+
+- [README.md](../../README.md) 已补齐 Claude、Codex、custom overlay 场景和输出模板入口。
+- [team-skills-usage.md](team-skills-usage.md) 已补齐 overlay、runbook、toolkit 的最短入口与阅读顺序。
+-  已补齐正式 custom overlay、runbook、toolkit 的分层说明和回落规则。
+- [custom-overlay.md](custom-overlay.md) 已从“company + runbook”扩展为“company + runbook + toolkit”的最短判断路径。
+- [batch-optimization-completion-checklist.md](batch-optimization-completion-checklist.md) 当前文档已作为本轮收口入口。
+
+### 1.2 当前结果
+
+- 用户现在可以从总入口直接判断一个能力应该进入 company、runbook 还是 toolkit。
+- custom overlay 场景不再只覆盖 私有流程、权限集成、GitLab、Langfuse，也明确覆盖 biz-service-designer 这类设计态 toolkit。
+
+## 2. Examples 层补齐
+
+### 2.1 Claude / Codex 场景示例
+
+- 已新增 [../../examples/claude-scenario-playbook.md](../../examples/claude-scenario-playbook.md)。
+- 已新增 [../../examples/codex-scenario-playbook.md](../../examples/codex-scenario-playbook.md)。
+- 已补齐 [../../examples/claude-conversation-script.md](../../examples/claude-conversation-script.md) 与 [../../examples/codex-conversation-script.md](../../examples/codex-conversation-script.md) 的 company 跳转入口。
+- 已补齐 [../../examples/role-conversation-scripts.md](../../examples/role-conversation-scripts.md) 的 QA、DevOps、Architect 场景补入口。
+
+### 2.2 Company / Toolkit 专项示例
+
+- 已新增 [../../examples/enterprise-overlay-scenario-playbook.md](../../examples/enterprise-overlay-scenario-playbook.md)，覆盖私有流程、权限集成、GitLab、Langfuse、biz-service-designer 的起手句。
+- 已新增 [../../examples/enterprise-overlay-output-playbook.md](../../examples/enterprise-overlay-output-playbook.md)，覆盖 `/handoff`、`/team-review`、`/team-release` 与 toolkit 结果回落。
+- 已更新 [../../examples/INDEX.md](../../examples/INDEX.md)，补齐 overlay / runbook / toolkit 路径与学习顺序。
+
+### 2.3 Biz Service Designer 完整示例
+
+- 已新增 [biz-service-designer-end-to-end-conversation-example.md](biz-service-designer-end-to-end-conversation-example.md)。
+- 已补齐 [biz-service-designer-toolkit.md](biz-service-designer-toolkit.md) 到完整对话样例的入口。
+
+### 2.4 当前结果
+
+- examples 层已形成四层结构：项目模板、线性会话脚本、场景 playbook、company/toolkit 专项示例。
+- company 与 toolkit 场景不再散落在多个模板说明里，而是有统一入口和统一回落方式。
+
+## 3. LLM Surface Reduction 收敛
+
+### 3.1 已完成的收敛结果
+
+- Shared skills 已收敛到 3 个：`api-contract`、`frontend-engineering`、`frontend-ui-ux-system`。
+- ECC skills 已收敛到 9 个高价值工具链入口，其中新增 `error-experience-library` 与 `parallel-execution` 两个运行时增强能力。
+- 公开命令已收敛到主链与少数 specialist 高识别度入口。
+- 通用模板已收敛，字段要求回写到规则和 runbook。
+
+### 3.2 已拆分的计划文档
+
+- [../plans/llm-surface-reduction-audit.md](../plans/llm-surface-reduction-audit.md)：只保留结论与判定原则。
+- [../plans/llm-surface-reduction-execution-checklist.md](../plans/llm-surface-reduction-execution-checklist.md)：只保留可执行清单。
+- [../plans/llm-surface-reduction-execution-history.md](../plans/llm-surface-reduction-execution-history.md)：只保留执行历史。
+
+### 3.3 当前结果
+
+- 减法主线已经完成，不再建议继续大规模删减。
+- 后续更适合做入口收敛、示例补齐和新增对象的前置审查。
+
+## 4. 当前平台状态
+
+最新校验后的状态如下：
+
+- Roles: 8
+- Shared skills: 3
+- ECC skills: 9
+- Private overlay skills: not shipped in public repo
+- Specialist agents: 27
+- Generated artifacts: 69
+
+## 5. 运行时与演示能力补齐
+
+### 5.1 已补齐的运行时说明
+
+- 已把 `scripts/hooks/session_start.py`、`session_end.py`、`pre_compact.py`、`suggest_compact.py` 回接到 [ecc-harness-usage.md](ecc-harness-usage.md) 与 [team-skills-usage.md](team-skills-usage.md) 的正式入口。
+- 已把 [error-experience-usage.md](error-experience-usage.md) 与 [parallel-execution-usage.md](parallel-execution-usage.md) 纳入总导航，避免新能力只存在于文件树里。
+
+### 5.2 已补齐的演示与汇报材料入口
+
+- 已把 [demo-scenario.md](demo-scenario.md) 与 [demo-execution-log.md](demo-execution-log.md) 纳入阅读入口，方便团队直接演示完整主链。
+- 已补齐 [../presentation/README.md](../presentation/README.md)，统一说明 PPTX 成品与生成脚本用途。
+
+## 6. 后续建议
+
+如果要继续做优化，优先顺序建议如下：
+
+1. 继续清理剩余 runbook 入口页，把新增 examples 与 toolkit 示例补齐到更多阅读路径。
+2. 新增对象时先按 [../plans/llm-surface-reduction-audit.md](../plans/llm-surface-reduction-audit.md) 的原则判断，避免重新引入薄包装层。
+3. 若后续 overlay 层再增加 profile、toolkit 或脚本型能力，优先复用当前 overlay / runbook / toolkit 三分法，而不是重新造一层 skill。

package/docs/runbooks/biz-service-designer-end-to-end-conversation-example.md

@@ -0,0 +1,5 @@
+# Biz Service Designer End To End Conversation Example
+
+该企业设计型对话示例已迁移到私有 `enterprise` overlay 仓库。公开仓仅保留占位说明。
+
+公开安装与 overlay 约定见 [custom-overlay.md](custom-overlay.md)。

package/docs/runbooks/biz-service-designer-toolkit.md

@@ -0,0 +1,5 @@
+# Biz Service Designer Toolkit
+
+该企业业务服务设计 toolkit 已迁移到私有 `enterprise` overlay 仓库。公开仓不再分发相关资料与脚本。
+
+公开安装与 overlay 约定见 [custom-overlay.md](custom-overlay.md)。

package/docs/runbooks/bug-fix-complete-walkthrough.md

@@ -0,0 +1,60 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# Bug 修复全流程演练
+
+本文演示一个典型 bug 如何从问题确认一路走到验证和收口，适用于 Claude 和 Codex。
+
+## 1. 场景
+
+- 问题：订阅页在 iPad 横屏下布局溢出
+- 影响：按钮被挤压，部分文案不可见
+- 不涉及：接口和数据库改造
+
+## 2. 推荐链路
+
+轻量问题可走短链路：
+
+1. `/team-intake`
+2. `/team-execute`
+3. `/code-review`
+4. `/handoff`
+5. `/team-review`
+
+如果问题影响范围大，再补 `/team-plan`。
+
+## 3. 输入示例
+
+```text
+/team-intake
+目标：修复订阅页在 iPad 横屏下的布局溢出
+范围：页面布局、响应式验证、UI 自测证据
+不做：接口改造
+约束：必须附带 ui-review-checklist
+```
+
+## 4. execute 阶段的关键输出
+
+- 根因说明
+- 改动范围最小化
+- 响应式自测证据
+- 是否存在其他断点回归风险
+
+## 5. review 阶段的关键输出
+
+- bug 是否真正复现并修复
+- 是否引入新的视觉回归
+- 是否仍有设备覆盖缺口
+
+## 6. 常见错误
+
+- 只说“修了样式”而不说明根因
+- 没有任何设备或断点验证证据
+- 把小 bug 修复也写成很重的长链路
+
+与前端专项说明配合阅读：[frontend-engineer-daily-operations.md](frontend-engineer-daily-operations.md)

package/docs/runbooks/build-failure-recovery-walkthrough.md

@@ -0,0 +1,40 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# 构建失败处理演练
+
+本文演示构建失败或校验失败时，如何定位、修复、复验并把问题结构化回收到主链。
+
+## 1. 场景
+
+- 构建脚本失败
+- 校验脚本失败
+- 文档链接或生成产物不一致
+
+## 2. 推荐链路
+
+1. `/team-execute`
+2. `/build-fix`
+3. `/verify`
+4. `/handoff`
+5. `/team-review`
+
+## 3. 关键输出
+
+- 根因定位
+- 修复动作
+- 复验结果
+- 是否存在剩余风险
+
+## 4. 常见错误
+
+- 只修表象，不记录根因
+- 构建恢复后不补复验
+- 没把失败影响范围说明白
+
+与这些文档配合阅读：[specialist-commands-playbook.md](specialist-commands-playbook.md)、[codex-workflow-essentials.md](codex-workflow-essentials.md)

package/docs/runbooks/canary-decision-matrix.md

@@ -0,0 +1,41 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# 灰度决策表与症状速查
+
+本文用于灰度过程中快速判断是继续放量、暂停观察还是回滚。
+
+## 1. 决策矩阵
+
+| 现象 | 建议动作 |
+|------|----------|
+| 指标稳定、无新增错误 | 继续按计划放量 |
+| 指标轻微波动，但仍在阈值内 | 暂停放量，继续观察 |
+| 错误率明显上升或关键路径失败 | 立即停止放量，评估回滚 |
+| 用户反馈与监控同时异常 | 优先回滚或限流 |
+
+## 2. 重点观察
+
+- 错误率
+- 接口耗时
+- 关键业务成功率
+- 前端主路径反馈时延
+
+## 3. 常见症状
+
+- 新错误集中在某个权限或特定端
+- 成功率下降但系统未完全不可用
+- 页面可打开，但关键动作失败
+
+## 4. 常见错误
+
+- 只看技术指标，不看业务成功率
+- 发现波动后继续放量
+- 暂停放量后没有明确下一次判断时间点
+
+相关长文档见：[canary-staging-release-walkthrough.md](canary-staging-release-walkthrough.md)、[pre-release-checklist.md](pre-release-checklist.md)

package/docs/runbooks/canary-staging-release-walkthrough.md

@@ -0,0 +1,46 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# 金丝雀灰度发布演练
+
+本文演示一个正常版本如何通过 staging、灰度、全量三个阶段安全发布。重点是观察指标、放量条件和回退条件。
+
+## 1. 场景
+
+- 功能已完成，准备按计划发布
+- 变更影响核心链路，不适合直接全量
+- 团队需要一份可执行的灰度方案
+
+## 2. 推荐链路
+
+1. `/team-plan`
+2. `/team-execute`
+3. `/verify`
+4. `/handoff`
+5. `/team-release`
+
+## 3. 关键输出
+
+- staging 验证结论
+- 灰度比例和观察窗口
+- 放量条件与终止条件
+- 回滚条件和责任人
+
+## 4. 合格结果的检查点
+
+- 指标和阈值明确
+- 放量步骤明确
+- 出问题时能快速停止或回退
+
+## 5. 常见错误
+
+- 灰度只写比例，不写观察指标
+- 放量节奏过快
+- 回滚条件没有提前约定
+
+与这些文档配合阅读：[devops-engineer-daily-operations.md](devops-engineer-daily-operations.md)、[hotfix-emergency-release-walkthrough.md](hotfix-emergency-release-walkthrough.md)