用途:在系统化调试确认一个已验证修复后,撰写该 bug 的标准工程记录,供其他工程师和未来的自己快速恢复心智模型。面向工程真相,不是管理层摘要。
触发方式:输入 /post-mortem,或说“write the post-mortem”“postmortem”“RCA”“root cause analysis”“document this fix”“write up the root cause”“close out this bug”。当调试流程落地一个已验证修复后,可主动提议起草。
使用前提(四项必须全部满足,缺一即列出缺失项并停止,不得起草):可靠复现(确定性或高概率 flaky,他人可运行);根因已知(机制已识别,非假设);修复已确定(存在 PR、commit 或分支指针);修复已验证(原复现通过,失败测试或负载成功)。原始素材来自调试流程的 breadcrumb ledger。
结构(按序):1 Summary(必填,一段话,说明用户或负载层面坏在哪、一句话修复、issue ID、PR 号、owner);2 Symptom(实际观察到的测试输出、错误信息、日志、性能数字等具体标识);3 Root cause(必填,真实机制,期望出现函数名、文件路径、结构体字段、分支条件、commit SHA,走完因果链);4 Why it produced the symptom(连接根因与症状);5 Fix(必填,改了什么、为何解决根因而非掩盖症状,附 PR 或 commit,若此前修复只是掩盖则点名说明);6 How it was found(简短调试路径,含假设与排除理由,写给别人可学习);7 Why it slipped through(CI 缺口、潜伏代码、负载缺口、此前修复不完整、评审遗漏,或无正当理由就直说;无指责);8 Validation(必填,具体测试名、运行链接、配置、修复前后性能数字,只验证一种配置就明确说明);9 Action items(具体下一步:做什么+owner+跟踪载体;没有就写“None — the fix is sufficient and no class-of-bug follow-up is warranted.”)。
语气:工程师对工程师;保留代码标识符;讲机制不叙事;主动语态、短段落;不用“we believe”“appears to”“may have”等模糊措辞;无指责;不做倡议,更大重构另写提案并在行动项中链接。
输出流程:确认四项输入;确认目标位置(默认 docx/postmortems/<bug-name>.md,也可为 issue tracker 评论、PR 描述、内部 wiki);以单一块输出草稿;向 issue tracker 回帖须先展示确切内容并等待明确许可后才发布,仅打印无需批准;起草后主动提议可交接 explain-in 生成面向管理层的版本,但不自动执行。
限制:缺陷未修复或修复未验证时拒绝起草,因为假设的复盘会误导;客户可见的故障或事故需单独的事件报告,覆盖时间线、影响范围、告警历史和沟通,此技能仅为缺陷修复范围;无关紧要的一行修复不写,PR 描述即记录;不得编造根因、owner、验证运行或行动项,事实缺失应询问;不得删除代码标识符。