review-core

核心审查工作流

适用场景

• 在任何详细审查工作流开始时使用（例如审查架构、数学内容或 API）。
• 它提供了一套一致的结构，用于记录上下文、整理证据和组织最终报告，让不同审查的结果可以相互比较。

不适用场景

• 以差异为重点的分析——使用 diff-analysis

激活模式

触发关键词：review、audit、analysis、assessment、evaluation、inspection 上下文线索：

• “审查这段代码／这个设计／这套架构”
• “对……进行审计”
• “分析其中的问题”
• “评估……的质量”
• “开展评估”

自动加载条件：检测到任何特定于审查的工作流，或有人请求分析方法时。

必需的进度项

1. review-core:context-established
2. review-core:scope-inventoried
3. review-core:evidence-captured
4. review-core:deliverables-structured
5. review-core:findings-verified
6. review-core:contingencies-documented

步骤 1 – 建立上下文（review-core:context-established）

• 确认 pwd、仓库、分支和上游基准（例如 git status -sb、git rev-parse --abbrev-ref HEAD）。
• 记录比较目标（合并基准、发布标签），以便后续差异引用明确的范围。
• 总结正在审查的功能／缺陷／计划，以及相关利益方和截止日期。

步骤 2 – 清点范围（review-core:scope-inventoried）

• 列出本次审查涉及的产物：源文件、配置、文档、规范、生成的资源（OpenAPI、Makefiles、ADR、notebooks 等）。
• 记录清点方式（例如使用 rg --files -g '*.mk'、ls docs、cargo metadata 等命令）。
• 记录从计划／问题单继承的假设或约束，便于领域专属分析引用。

步骤 3 – 收集证据（review-core:evidence-captured）

• 记录所有为审查提供依据的命令／输出（例如 git diff --stat、make -pn、cargo doc、web.run 引用）。保留片段或行号，以便后续查阅。
• 跟踪预检时发现的未决问题或差异；如果它们阻碍进度，现在就记录负责人和时间安排。

记录经验教训（决策日志）

如果此项工作涉及返工、失败的方法或阻碍，请将其记录到 docs/lessons-learned.md，让经验能在本次会话结束后留存（起草并确认）：

• 如果已安装 leyline，调用 Skill(leyline:decision-journal) 并追加一条经验记录（what_happened、what_didnt_work、root_cause、action； 将 phase 设为 review）。展示草稿；确认后再追加。
• 备用方案（未安装 leyline）：使用文件内的 ENTRY TEMPLATE 追加到 docs/lessons-learned.md； 分配下一个 LL-NNN ID。

步骤 4 – 组织交付内容（review-core:deliverables-structured）

• 准备所有审查共用的报告框架：
  • 摘要（基准、范围、建议）
  • 按顺序排列的发现（严重程度、文件:行号、违反的原则、修复措施）
  • 后续任务（负责人 + 截止日期）
  • 证据附录（命令、URL、notebooks）
• 结束前，验证领域专属检查清单能否填充每个章节。

步骤 5 – 验证发现有据可依（review-core:findings-verified）

每条发现都必须可证伪：第二轮审查时，可通过引用逐字核对并确认。未通过验证的发现不得提交。

• 使用 Skill(imbue:structured-output) 中的有据发现架构：每条发现都包含一个 Location（file:line）和一段从该行原样复制的 Anchor 片段。

• 将发现写入 .review/findings.json（每条发现对应一个对象，包含：id、file、line、anchor、severity、category、recommendation、evidence_refs）。

• 运行验证器：

  python plugins/imbue/scripts/citation_verifier.py \
    --findings .review/findings.json --repo-root .
  

  退出码 0 表示所有引用均已解析；退出码 1 会列出路径、行号或锚点与源文件不匹配的每条发现。

• 对验证器判定失败的发现，予以删除或标记为 UNVERIFIED；报告中只能包含已验证的发现。将验证器输出附在证据附录中。

• 如果脚本不可用，则手动重新阅读每条引用的 file:line，并确认其中包含锚点文本；在应急预案部分注明采用了手动替代方案。

步骤 6 – 应急预案（review-core:contingencies-documented）

• 如果所需工具或技能不可用（例如 web.run），请记录将采取的替代步骤及其带来的任何限制。这有助于审查者了解覆盖范围中存在的缺口。
• 记录尚待完成审查所需的任何审批或数据。

退出条件

• 所有进度项均已完成，并附有具体记录（运行的命令、列出的文件、证据路径）。
• 每条报告的发现都包含 Location 和原样引用的 Anchor，并已通过 citation_verifier.py 确认（或记录了手动重新阅读）。不得提交未经验证的发现。
• .review/findings.json 已存在，且验证器退出码为 0；或者所有验证失败的发现均已删除或标记为 UNVERIFIED。
• 在开始任何特定领域的审查之前，必须先准备好上下文、证据日志和交付物模板。
• 在收集证据期间发现的任何返工、失败的尝试或阻碍因素，都记录在 docs/lessons-learned.md（或文件内模板）中。