用途
当工作进入评审环节时,PR 正文是会话之外的评审者唯一会读的产物。该技能把纸面痕迹中已经存在的信息组装成 PR 正文,不添加任何尚未确立的内容。其 summary-visual 纪律受 show-me 启发(在 frontmatter 中致谢)。
模板
## Summary
<one-line claim, then the smallest visual that proves it>
## Evidence
- **Before:** <output / failing check>
**After:** <output / passing check>
## Reversibility
<Rollback: cheap via <mechanism> | expensive because <reason>>
<Blast radius: one line>
各部分说明
Summary
用一句话陈述变更,然后展示能说明该点的最小视图。可视化形式要与变更类型匹配:
- 逻辑或算法 → 伪代码
- 运行时控制流 → 调用树
- UI 结构 → 组件树
- 文件职责或大范围重构 → 浅层文件树
- 组件交互或数据流 → Mermaid 图
- 变更本身 → 与变更形态一致的 diff(组件、布局、调用树或状态机)
仅当大部分内容都是新增、省略上下文会隐藏归属关系,或评审者需要一个可复制的目标形态时,才展示完整代码块。通常一个可视化就足够,绝不要使用所有形式。
Evidence
消费 verify 协议的输出——BUILD、TEST、LINT、FUNCTIONALITY 证据,并继承其新鲜度规则。以 before/after 成对呈现:变更前失败、变更后通过的确切检查,直接引用输出本身。当变更是视觉性的,优先使用截图;qa-tester 可以驱动运行时获取一张。不要在此重新采集证据,也不要声称 verify 环节未产出的证据。
Reversibility
对 diff 本身运行 ADR 测试——与 launch 应用于决策的同样三个问题:难以逆转?脱离上下文会令人意外?是真实权衡的结果?三个都回答“否”即为廉价回滚:说明通过什么机制(回滚合并、切换开关)。任何一个回答“是”即为昂贵回滚:说明原因。先对门分类:双向门(撤销廉价且常规)除命名撤销方式外无需额外仪式;单向门则明确说明,并指出使该步骤不可逆的原因。当变更实现或触及某个 ADR 时,链接该 ADR。最后用一行给出影响范围——该变更还可能牵动什么。
语言
术语来自 GLOSSARY.md(若存在词汇表);尚未迁移的旧项目将其保留在 CONTEXT.md 中。PR 在会话之外被阅读,词汇表是读者与它共享的唯一词汇。
触发条件
- launch 第 5 阶段,当平台通过 PR 进行评审时:完成报告携带由该技能起草的 PR 正文。
- 任何打开或实质性更新 PR 的会话。
输出
- 可直接粘贴的 PR 正文
- 它所依赖的纸面痕迹指针(verify 证据、ADR、spec)