review-patterns

name	review-patterns
description	Pattern library for code review reading-guide artifacts. Provides five template skeletons (trace, layer, data, state, storyline) that each anchor the reader on a different mental model.

Review Patterns

代码评审型 artifact 的模式库。目标：带读用户理解 content，而不是审计 content。

核心立场

维度	旧式"问题清单"评审	本插件的「带读式」评审
输出主语	"代码里有什么问题"	"怎么把这段代码读懂"
锚点要求	可选	每条结论必须有 file:line
语气	下结论（这里有 bug）	带读（此处逻辑是 X，需确认 Y）
末尾	review checklist	reviewer_questions（开放追问）

5 个模板

每个模板给读者一个不同的精神锚点。

---

Template A — trace（执行链路追踪）

锚点 = 一条完整的执行流。从入口逐步走到终点，每步附代码原文 + 当下的内部状态。读完读者把一次请求走了一遍。

IR 骨架

## scope_summary

## entrypoint
- name + file:line
- 入口形态：HTTP handler / 消息消费 / 定时任务 / CLI
- 触发条件

## trace_steps
按时间顺序的 step 列表，每个 step：
- order: 1, 2, 3 ...
- anchor: file:line
- code_excerpt: 该步的代码原文（精简到关键行）
- action: 这步做了什么（一句话）
- state_after: 此刻系统/数据的状态（可省略）
- branches: 该步存在的岔路（错误路径、并发分支）单列子项

## terminal_states
- 正常终点：响应内容、副作用、持久化结果
- 异常终点：各错误分支的最终落点

## reviewer_questions
读完链路后建议追问的开放性问题

渲染指南

• 主区采用纵向 step list，左侧大序号 + 锚链接，右侧两列（代码 / state 注解）
• 每个 step 用 <section> 包裹，左侧导航列出 step 标题
• 岔路用嵌套缩进或折叠子卡片

---

Template B — layer（自顶向下剥层）

锚点 = 架构层次。从最外层 public API 开始，每往下一层说明"职责变换"。读完掌握分层结构。

IR 骨架

## scope_summary

## layer_overview
- 层数清单（Layer 0..N）+ 一句话职责
- 整体分层图（用 architecture_diagram 类型）

## layers[]
每个 layer：
- name: Layer N — <职责>
- boundary: 这一层接受什么、产出什么
- key_functions: [{name, anchor, one_liner}]
- responsibility_shift: 从上一层到本层"职责发生了什么变化"
- error_strategy: 这一层如何处理上传 / 下传错误

## cross_cutting
跨层关注（日志 / 度量 / 鉴权 / 事务）单独成段，列出散落在各层的实现锚

## reviewer_questions

渲染指南

• 主区为自上而下分层卡片，每层独立 <section>
• 每层内含小标题（boundary / key_functions / responsibility_shift / error_strategy）
• 左侧导航第一组列出 Layer 0..N，第二组列出 cross_cutting

---

Template C — data（数据生命周期）

锚点 = 一个核心名词的生命周期（订单 / 会话 / 事件 / 任务等）。追踪它从出生到消亡。读完读者对核心数据结构有肌肉记忆。

IR 骨架

## scope_summary

## data_object
- name + 类型定义锚 (file:line)
- 字段一览（关键字段 + 含义 + 来源）
- 携带的不变量

## lifecycle_timeline
按时间顺序的事件列表：
- phase: birth / mutation / persistence / read / cleanup / death
- anchor: file:line
- transformation: 这一刻数据从什么样变成什么样
- triggered_by: 谁触发了这次变化

## storage_facets
- 存储形态：内存 / DB / 缓存 / 消息队列 / 文件
- 各处对该数据的不同表示（DTO / Entity / Wire format）+ 转换函数锚

## edge_cases
- 同一数据在异常路径下的命运（事务回滚、缓存失效、消息重试）

## reviewer_questions

渲染指南

• 主区用纵向时间线（左侧 phase 徽章），每个 phase 节点一个卡片
• 字段一览用表格，含「字段 | 类型 | 含义 | 出生地 (anchor)」
• storage_facets 用 tabs 切换不同存储

---

Template D — state（状态机视图）

锚点 = 状态与转移。适合工作流 / 会话 / 长生命周期对象。所有状态画成图，每条转移挂代码锚。读完读者完全理解"这玩意能处于哪些状态、怎么变"。

IR 骨架

## scope_summary

## state_definition
- 状态枚举（含 file:line）
- 每个状态的语义注释
- 初始状态、终止状态

## state_diagram
节点 = 状态，边 = 转移：
nodes: [{id, label, kind: initial|normal|terminal}]
edges: [{from, to, trigger, anchor: file:line}]

## transition_table
- from → to · trigger · guard · code_anchor · side_effects

## invariants
- 在任何状态下都成立的约束（不变量）+ 校验位置

## illegal_or_missing
- 不存在的转移（应当被代码拒绝）+ 拒绝位置
- 不存在但可能应当存在的转移（带读者注意空白）

## reviewer_questions

渲染指南

• 主区左侧 inline SVG 状态图（必含 .zoomable + 全屏按钮）
• 右侧或下方为转移表 + 不变量 + illegal_or_missing
• 状态图节点点击锚跳转到对应转移行

---

Template E — storyline（变更叙事，仅 PR / diff）

锚点 = 改动背后的意图。重建叙事：问题 → before → after → 每个 hunk 的角色 → 涟漪。

约束：只能配合 source_type=pr 或 diff。其他源类型选此 template 必须立即终止。

IR 骨架

## scope_summary

## intent
- 改动想解决什么（从 PR title / body / commit msg / 关联 issue 推断）
- 推断来源（标注是引用还是推断）

## before_after
- before_snippet: 关键变更点修改前的样子（含 file:line）
- after_snippet: 修改后的样子（含 file:line）
- diff_summary: 整体改了什么（一句话）

## hunk_roles
每个 hunk 一条：
- anchor: file:line
- role: core_fix / new_feature / refactor / test / config / chore
- summary: 这个 hunk 单独承担什么
- depends_on: 同 PR 内依赖的其他 hunk id（如有）

## ripple_effects
- 影响的调用方（grep 找到的外部 caller）
- 是否破坏向后兼容
- 配置 / schema / API 契约变化

## tradeoff_points
作者做出的取舍（不下结论，只指出）：
- anchor: file:line
- 选择了什么、舍弃了什么、为什么可能这么选

## reviewer_questions

渲染指南

• 主区顶部上下双栏 before / after 代码
• 中部 hunk 列表，每条左侧色块（按 role 着色）
• 下部 ripple_effects + tradeoff_points 表格

---

模板选择指南（当用户没指定 --template）

默认 trace，因为它最通用。但以下信号建议提示用户切换：

• 发现强分层结构（明显 controller/service/repo 命名）→ 推荐 layer
• 单一核心类型在多文件流转（如 Order 出现 > 5 次跨文件）→ 推荐 data
• 出现状态枚举 / FSM / Workflow 字样 → 推荐 state
• 输入是 pr: 或 diff → 推荐 storyline

通用约束（所有模板共享）

• 每条结论挂 file:line 或 (no anchor) 显式标注
• 不下结论，带读理解：用"此处逻辑是 X，评审时确认 Y"代替"这里有 bug"
• 通用首章 scope_summary、通用末章 reviewer_questions
• 长内容不删减，配合左侧导航与折叠区分块
• 图表外层套 .zoomable 全屏按钮