Contest Retrospective

---
name: contest-retrospective
description: "赛后/项目后复盘与经验沉淀：从留痕取证分类典型场景、踩坑与交付清单，归因真实强制点，双写经验库并机检闭环。触发词：复盘、赛后总结、经验沉淀、教训清单、事故归因、post-mortem、retrospective、把教训写进项目、避免下届重踩、lessons learned、根因分析、强制点归因。"
agent_created: true
---

# 赛后复盘与经验沉淀（contest-retrospective）

**一句话**：把"这次踩的坑"变成"下届踩不到的坑"。
判据只有一条——**每条教训都必须绑定一个仓库内真实存在的强制点**（代码 / 规则 / 模板）。
没有强制点的教训不算沉淀完成，它会在下一届原样复发。

## 何时用

- 一次真实参赛（CUMCM/MCM/统计建模赛等）或项目 run 结束后，需要把事故与决策固化进工具箱。
- 出现"上次就吃过这个亏"的重复事故——说明上届复盘只停在记忆层，没落到强制点。
- 收到一份外部诊断报告/审计报告，需要判断哪些结论成立、哪些要驳（**批判式吸收**，见 §3）。

**不用于**：赛事成绩申诉、论文正文修改、单纯的事故陈述（不落强制点的报告不收）。

## 0. 输入契约

| 输入 | 必需 | 说明 |
|------|------|------|
| 工作区路径 | ✅ | 待复盘的工作区（含 `.engine/`、产物、交付文档） |
| 复盘范围 | 可选 | 默认全链路；可限定为某个阶段（day1/day2/day3/submission） |
| 既有经验库 | ✅ | `academic-toolkit/data/contest_lessons.{json,md}`（不存在则按其 schema 新建） |
| 外部诊断报告 | 可选 | 第三方报告；**必须逐条研判，不得整篇照抄** |

## 1. 取证（不信任自述）

**只从留痕取证**，任何人（含 agent 自己）的口头总结都不算证据：

```
待取证清单（存在即读，缺失即记录"缺失"——缺失本身是证据）
  .engine 审计日志                    L1 实际工具调用（工作区内，运行时生成，agent 不可绕过）
  .engine/evidence/*.json             L3 执行申报（命令/产物/哈希）
  STEP_MANIFEST.json                  输入输出哈希与命令
  engine_step.log / run_*.json        工作流推进与停滞
  workspace/STATE.txt                 版本与取代关系
  交付文档（HANDOVER/DELIVERY_NOTES/审计报告/自检报告）
```

取证纪律：
1. **交叉验证**：申报（L3）与实测（L1/产物）必须对得上；对不上就是一条待复盘项。
2. **不信"全部门禁通过"**：门禁通过只说明当时检查项的全集，不说明覆盖了本次的风险面。
3. **缺失即证据**：某类留痕整体缺失（如后 N 步无 `STEP_MANIFEST`）本身就是最高优先级的坑。

## 2. 分类（三条产线）

| 产线 | 判定 | 字段要求 |
|------|------|----------|
| **典型场景**（scenarios） | "遇到 X → 怎么判 → 为什么这样判" | `trigger` / `decision` / `rationale`（决策依据是本库最有价值的部分） |
| **踩坑**（pitfalls） | 已发生且有留痕证实的缺陷 | `severity`(P0/P1/P2) / `symptom` / `root_cause` / `impact` / `prevention` |
| **交付清单**（checklists） | 上传/交付前的逐项硬闸 | `items`（≥4 项，且每项可执行、可判定） |

严重度口径：
- **P0** = 直接失分 / 取消资格级，或证据链整体失效；
- **P1** = 高概率返工，或审计不可用；
- **P2** = 体验与健壮性，长期累积成隐性风险。

## 3. 归因到强制点（本技能的灵魂）

每条条目**必须**给出 `enforced_by` —— 仓库根相对路径，指向真实存在的强制点：

```
缺陷：正文页数超限晚期才发现
  → 强制点：academic-toolkit/skills/_utils/quick_gates.py        （门禁前移）
缺陷：审核产物可被主 Agent 手写伪造
  → 强制点：academic-toolkit/engine/workflow_runner.py            （requires_subagent 强校验）
缺陷：推荐技能用与不用零留痕
  → 强制点：academic-toolkit/engine/workflow_runner.py            （C1 强制申报 + 痕迹绑定）
```

**找不到强制点怎么办**（三条出路，按优先级）：
1. **补强制点**：把约束写成代码/机检/模板声明（首选，本技能的主要价值在此）；
2. **显式挂账**：在条目 `prevention` 写清"待补"，并在 `dev-docs` 缺陷台账登记——但该条目
   不得申报为"已沉淀"；
3. **降级为场景**：如果它不是可机检的缺陷而是判断经验，挪到 `scenarios`（决策依据天然不需要强制点）。

**禁止**：写"应当建立 XXX 机制"这类无落点承诺；把根因不同的多条合并成一条（会掩盖真因）。

## 4. 批判式吸收外部报告

收到第三方诊断报告时，逐条给三种判定之一，并附自己的证据：

| 判定 | 含义 | 处理 |
|------|------|------|
| **成立** | 证据与该报告的结论一致 | 收录为坑，归因强制点 |
| **半成立** | 现象成立但归因错（例："6 个产物缺失=流程没走"，实为"缺标准文件名归集，实质工作已在 review/ 留档"） | 拆成两条：现象条 + 归因修正条 |
| **不成立** | 报告忽略的既有机制使其失效（例：声称"工作流不要求使用 skills"，而 runner 每步都带推荐提示） | 记录为"已驳"，写清反证路径，**不入坑清单** |

> 批判式吸收的产物是"修正表"（原结论 / 研判 / 证据），比照单全收更有价值。

## 5. 双写与机检（完成定义）

```bash
# 双写：JSON（机器真源）与 MD（人读真源）同改，ID 一一对应
#   data/contest_lessons.json  ← 结构化字段
#   data/contest_lessons.md    ← 决策叙述（同一 ID 必须出现）

python academic-toolkit/tools/contest_lessons_check.py --strict   # schema + 强制点在位 + 双向一致
pytest academic-toolkit/tests/test_contest_lessons.py -q           # 回归护航
```

三条硬判据：
1. `--strict` 退出码 0；
2. 强制点全部在位（无"空话"条目）；
3. 强制点分布不过度集中（单文件覆盖 >60% 条目时工具告警——说明经验其实只落在一个机制上）。

## 6. 回灌（让结论离开一次性报告）

沉淀不止于经验库，可迁移结论必须并入**承载它的技能**：

| 结论形态 | 回灌位置 |
|----------|----------|
| 某步骤的操作规范 | 对应 `skills/<name>/SKILL.md`（步骤/铁律段） |
| 资产/技能/配色等登记类 | `engine/modex-core/templates.json` 对应步骤 `metadata` |
| 新工具/新机检 | `tools/` + `tests/` + `AGENTS.md` 工具链调用规范 |
| 跨届可复用的判断经验 | 本经验库 `scenarios` |

回灌后必须复跑受影响测试（改模板跑 `tools/upgrade_templates.py` 验幂等 + 资产指针审计）。

## 7. 输出契约

| 产物 | 位置 | 判据 |
|------|------|------|
| 经验库（机器真源） | `academic-toolkit/data/contest_lessons.json` | schema 合规、ID 唯一、强制点在位 |
| 经验库（人读真源） | `academic-toolkit/data/contest_lessons.md` | 与 JSON ID 集合完全一致 |
| 取证清单 | 工作区或 dev-docs | 逐条列"读了什么/缺什么" |
| 批判式修正表 | dev-docs（若本轮研判了外部报告） | 每条含 成立/半成立/不成立 + 证据路径 |

## 8. 质量铁律（违反即返工）

1. **无强制点不称沉淀**——`enforced_by` 必须指向真实文件，机检会把空话打成失败。
2. **不合并异因**——不同根因的坑各占一条；同一根因的不同现象归到同一条的 `symptom`。
3. **不伪造留痕**——取证阶段读不到的东西写"缺失"，不写"推测"。
4. **双写同步**——只改 JSON 或只改 MD 都会被 `--strict` 拦下。
5. **一次事故一条**——把事故写进 `impact`，不要把事故写成标题情绪。
6. **回灌才算闭环**——只更新经验库而不回灌技能/模板，等于把结论继续留在报告里。

## 9. 自检清单

- [ ] 取证清单完成，缺失项已显式记录
- [ ] 每条坑有 severity / symptom / root_cause / impact / prevention
- [ ] 每条条目 `enforced_by` 指向真实存在的文件
- [ ] 外部报告（若有）已逐条研判并出修正表
- [ ] `contest_lessons_check.py --strict` 退出码 0
- [ ] `tests/test_contest_lessons.py` 全绿
- [ ] 可迁移结论已回灌对应 SKILL.md / templates.json
- [ ] 受影响测试已复跑（改模板额外验幂等与资产指针）