name: postmortem
description: Use when analyzing fix commits to create postmortems, checking code changes against known issues before release, or updating postmortem knowledge base after release. Triggers on /postmortem command with onboard, check, or update arguments.
argument-hint: "[onboard | check [base] | update [range]]"
metadata:
author: jerikchan
version: "1.0.0"

Postmortem 驱动开发

Overview

通过 postmortem（尸检报告）将 bug fix 的教训转化为可查询的知识库，在 Release 前检测可能触发已知问题的代码，形成持续学习的闭环。

核心原则： 每个 bug fix 都是一次学习机会，必须被记录、索引、并用于预防未来的回归。

命令用法

/postmortem onboard          # 初始化：分析历史 fix commits，创建知识库
/postmortem check [base]     # 检查：对比 base 分支，检测风险
/postmortem update [range]   # 更新：分析指定范围的 fix commits，更新知识库

When to Use

Postmortem 文档结构

每个 postmortem 存放在 ./postmortem/ 目录，使用 Markdown 格式：

---
id: PM-001
title: 简短描述问题
severity: critical | high | medium | low
created: 2024-01-15
updated: 2024-01-20
related_commits: [abc1234, def5678]
tags: [authentication, race-condition, async]
---

# PM-001: 简短描述问题

## 问题概述
一句话描述发生了什么问题。

## 影响范围
- 受影响的功能/模块
- 影响的用户范围

## 根本原因
详细分析为什么会发生这个问题。

## 触发条件
**关键！** 描述什么样的代码变更会触发类似问题：
- 特定的代码模式
- 特定的文件或模块
- 特定的操作序列

## 修复方案
实际采用的修复方法，包括代码示例。

## 预防措施
- [ ] 代码审查检查点
- [ ] 测试用例补充

## 经验教训
从这次事件中学到的可推广的经验。

模式 1: Onboard（初始化）

命令： /postmortem onboard

执行步骤

1. 创建目录结构
   bash mkdir -p postmortem

2. 扫描 fix commits
   ```bash
   # 通过 commit message 关键词识别
   git log --oneline --all | grep -iE "(fix|bugfix|hotfix|patch|resolve|修复|修正|解决)"

# Conventional Commits 格式
git log --oneline --all | grep -E "^[a-f0-9]+ fix((.+))?:"
```

1. 分析每个 fix commit
2. git show --stat <commit> - 查看变更的文件
3. git show <commit> - 查看具体变更内容

4. 从代码变更反推问题的根本原因

5. 将相似问题分组，避免重复创建 postmortem

6. 生成 postmortem 文档，使用上述文档结构

7. 创建 INDEX.md 索引文件

输出示例

./postmortem/
├── INDEX.md
├── PM-001-auth-race-condition.md
├── PM-002-null-pointer-in-parser.md
└── PM-003-timezone-calculation.md

模式 2: Check（Release 前检查）

命令： /postmortem check [base_branch]

执行步骤

1. 加载所有 postmortem 文档

2. 读取 ./postmortem/*.md（排除 INDEX.md）

3. 提取每个 postmortem 的触发条件

4. 文件路径模式
5. 代码模式

6. 操作序列

7. 获取代码变更
   ```bash
   # 对比 base 分支
   git diff --name-only $(git merge-base HEAD origin/main) HEAD

# 查看具体变更
git diff $(git merge-base HEAD origin/main) HEAD
```

1. 匹配触发条件
2. 文件路径匹配
3. 代码模式匹配

4. 语义分析

5. 生成检查报告

输出格式

# Postmortem Check Report

## 检查范围
- 基准分支: main
- 文件变更数: 15
- 检查的 postmortems: 5

## ⚠️ 风险警告

### PM-001: Auth Race Condition
**匹配原因:** `src/auth/session.ts` 被修改，且包含异步操作
**建议操作:**
- [ ] 确认新代码中的异步操作有正确的锁机制
- [ ] 运行相关测试用例

## ✅ 检查通过
- PM-002, PM-003, PM-004, PM-005: 无匹配的代码变更

模式 3: Update（Release 后更新）

命令： /postmortem update [commit_range]

执行步骤

1. 扫描指定范围的 fix commits
   ```bash
   # 指定 tag 范围
   git log v1.0.0..v1.1.0 --oneline | grep -iE "(fix|bugfix|hotfix|修复)"

# 最近 N 个提交
git log -20 --oneline | grep -iE "(fix|bugfix|hotfix|修复)"
```

1. 加载现有 postmortems

2. 分析每个 fix commit

3. 判断是否属于已有 postmortem（相似问题）

4. 决定更新现有文档还是创建新文档

5. 更新策略

6. 相似问题 → 合并到现有 postmortem，增加 related_commits
7. 新问题 → 创建新的 postmortem 文档

8. 问题再次出现 → 更新 postmortem，标记为需要关注

9. 更新 INDEX.md

Quick Reference

Common Mistakes

典型工作流

项目初始化
    └─→ /postmortem onboard
           └─→ 生成初始知识库

日常开发
    └─→ 准备 Release
           └─→ /postmortem check main
                  └─→ 检查风险，修复问题
                         └─→ Release
                                └─→ /postmortem update
                                       └─→ 沉淀新的教训