Entry/Exit
- Entry: Feature/milestone completed, incident handling finished, project phase ended
- Exit: Post-incident summary document + action items (trackable)
- Pointing to: Action items incorporated into the next plan/backlog
- Pre-load: CANON.md
- Output path: ship-workflow-ship (action items incorporated into backlog) / maintain-workflow-learn (lessons learned extraction and archiving)
When not to use
- The feature is not yet complete and is still in the build/review/ship stage
- It is only a routine small change, minor documentation tweak, or configuration fix
- There is no reviewable event, decision, or outcome evidence
When to do a retrospective
Must do: After each feature launch, after incident/severe bug fixes, at the end of a Sprint/milestone, after major refactoring is completed
Not necessary: Routine small changes, documentation updates, configuration adjustments
Retrospective structure
1. Timeline
Checkpoint: After the timeline is completed — Confirm that the timeline is based on verifiable facts (logs, deployment records, alerts), not pure memory. Cover at least four nodes: start, key decisions, issue discovery, fix deployment.
建立客观事实——按时间顺序列出发生了什么:
- 什么时候开始的
- 关键决策点在什么时间
- 问题什么时候发现的
- 修复什么时候部署的
Timeline first, then analysis. Skipping the timeline and analyzing directly = evaluation based on memory rather than facts.
2. What went well (keep)
Checkpoint: After the list of good practices is completed — Confirm at least 3 items, each explaining why it was good rather than giving vague praise.
List at least 3 things done right. This is not modesty — identifying good practices is the only way to repeat them.
3. Better (improvements)
Checkpoint: After the list of improvement points is completed — Confirm that each improvement point has a specific scenario and specific fix, rather than "X should be better".
Be specific. Not "communication should be better", but "the database schema change was not communicated to the frontend team, causing 3 hours of breakage. Next time there is a DB change → announce it in advance in the #frontend channel".
4. Action items
Checkpoint: After the action item list is completed — Confirm that each item has a single owner, a deadline, and a verifiable completion criterion. Vague action items must be rewritten.
Each action item must:
- Have an owner (one person, not "the team")
- Have a deadline or association with the next milestone
- Be verifiably complete ("improve test coverage" is not an action item; "add 3 integration tests for the payment module" is an action item)
Metric collection
Collect data during the retrospective to support discussion:
指标类别:
├── 功能/故事点完成数
├── 提交数 + PR 大小
├── 测试覆盖率变化
├── Bug 数量(引入的 vs. 修复的)
├── 上线到稳定时间
├── 回滚次数
└── 会议/同步消耗 vs 编码时间
Dedicated incident retrospective template
# 事故复盘: [标题]
## 时间线
- [HH:MM] 问题开始
- [HH:MM] 告警触发
- [HH:MM] 第一个响应者介入
- [HH:MM] 定位到原因
- [HH:MM] 修复部署
- [HH:MM] 服务恢复正常
## 影响
- 影响时长: XX 分钟
- 影响用户: XX / XX%
- 数据损失: 有/无
## 根因
[1-2 句]
## 5 Why
1. 为什么用户无法下单?→ 支付服务返回 500
2. 为什么支付服务返回 500?→ 数据库连接池满了
3. 为什么连接池满了?→ 新部署的代码有 N+1 查询
4. 为什么 N+1 没在审查中捕获?→ 代码审查没有检查查询性能
5. 为什么没有性能检查?→ 审查清单没有性能项
## 行动项
1. [owner] 修复 N+1 查询 — [date]
2. [owner] 给代码审查清单加性能专项 — [date]
3. [owner] 给支付服务加连接池监控告警 — [date]
Common excuses
| Excuse | Reality | Consequence |
|---|---|---|
| "Too busy, no time for a retrospective" | If you do not spend 30 minutes on a retrospective, the same problem will cost 8 hours next time. A retrospective is an investment. | The same type of problem recurs, each fix takes ≥ 8h, cumulative waste ≥ N x 8h |
| "The problem is obvious and does not need analysis" | The obvious is the symptom, not the root cause. After 5 Whys, the real cause is often found to be different from what was initially thought. | If only the symptom is treated and not the root cause, the probability of the same type of problem recurring within 3 months is ≥ 80% |
| "Action items will be discussed later" | Action items without an owner and deadline will not happen. Anyone should be assigned before the retrospective ends. | Action items without an owner will never be executed, and the same problem will appear in the next retrospective |
Red flags — STOP
- The retrospective turns into a blame game (whose fault it is) rather than system improvement
- Only listing the bad and not the good (seeing only problems = low morale)
- Action items are vague or have no owner / deadline
- The same problem appears in the retrospective for the second time (the previous action items were clearly not executed)
- No one is responsible for tracking the completion of action items
Verification failure handling
| Failure scenario | Handling method |
|---|---|
| The timeline is based on memory rather than facts | Require objective evidence such as logs, deployment records, alert screenshots, etc. Mark nodes without evidence as "to be confirmed" |
| The retrospective turns into a blame game | Immediately shift to a system improvement perspective. Ask "why did the system allow this error to happen" rather than "who made the mistake" |
| Fewer than 3 good practices | Expand the scope of observation—there are good practices in dimensions such as code quality, collaboration efficiency, degree of automation, and tool improvements |
| Action items have no owner or deadline | Assignment must be done before the retrospective ends. Action items without an owner are considered invalid and are not included in the backlog |
| The same problem appears for the second time | The root cause is that the previous action items were not executed. Track the execution status of the previous action items, confirm the blocking reasons, and then set a new deadline |
Good/Bad examples
Bad: vague retrospective
# 复盘: Q2 发布
做得不好:沟通不够,测试不足,上线出了问题。
改进:加强沟通,增加测试。
行动项:团队讨论改进方案。
Problem: no timeline, no specific improvements, no owner, no deadline—the same entries will appear in the next retrospective.
Good: trackable retrospective
# 复盘: Q2 发布
## 时间线
- 05/01 开始开发
- 05/10 DB schema 变更未通知前端
- 05/15 前端 3 小时 breakage
- 05/20 上线后 P99 延迟升至 500ms
- 05/22 修复部署
## 做得好
1. 自动化部署流水线节省 2 小时/次
2. 代码审查捕获了 3 个安全漏洞
3. 监控告警在 30 秒内通知团队
## 更好
1. DB 变更未通知前端 → 下次 DB 变更在 #frontend 频道提前公告
2. N+1 查询未在审查中捕获 → 审查清单加性能专项
## 行动项
1. [张三] 给审查清单加性能专项 — 05/30
2. [李四] DB 变更公告流程写入 README — 05/28
3. [王五] 给支付服务加连接池监控 — 06/01
Strengths: the timeline is based on facts, good practices can be repeated, improvement points are specific, and action items have owners and deadlines.
Output template
After the retrospective is completed, the following structure should be produced (saved to the docs/features// or docs/retro/ directory):
### Retro 交付记录
**复盘类型**: [功能上线 / 事故 / 里程碑 / 重构]
**复盘对象**: [功能名 / 事故标题 / 里程碑名]
**复盘日期**: [YYYY-MM-DD]
**参与人**: [列出参与者]
**时间线节点数**: [N]
**好做法数**: [≥ 3]
**改进点数**: [N]
**行动项数**: [N]
**行动项追踪表**:
| # | 行动项 | Owner | 截止日期 | 状态 |
|---|--------|-------|----------|------|
| 1 | [具体行动] | [人名] | [日期] | [待执行 / 进行中 / 完成] |
**归档路径**: [docs/retro/YYYYMMDD-<name>.md]
**关联 learnings**: [是否已提取到 .claude/learnings.jsonl]
Verification checklist
- The timeline is complete (it does not jump directly from memory to conclusions)
- At least 3 good practices are identified
- Improvement points are specific (not a vague "communicate better")
- Each action item has an owner + deadline
- The retrospective document is saved in a location that can be referenced
- If metrics are included—the metric data has a source rather than being estimated