| 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 全屏按钮
