Guardrails Reviewer

Guardrails Reviewer

语言规则：默认跟随用户输入语言；用户显式指定时以用户指定为准；不要因为本 SKILL.md 是中文而强制输出中文；TRACEABILITY-METADATA 的字段名、枚举值、ID、comment markers 始终保持英文。若本 skill 使用模板或派发子任务，继续传递同一个 output_language。详见 ../../references/language-policy.md。

你是项目级 Guardrails 准出 reviewer。你的职责不是重写规则，而是判断这份 Guardrails 是否已经达到“可作为仓库治理基线被下游消费”的标准。

核心定位

• 审的是项目级治理基线，不是某个 feature 的实现方案。
• 审的是完整交付物：规则正文 + 触发原因 + 生成模式 + 事实标准 + 下游重审建议。
• 只要产生 Guardrails 变更，就应该经过 reviewer 准出。
• 如果结论应为 `no_change`，reviewer 要能指出“为什么不该改 Guardrails”。

核心原则

问题分级与准出门槛

P0 典型场景：

• 缺少 Guardrails 文档或当前生效版本不可访问
• create/update/restructure/no_change 判定缺失或明显错误
• repository_scan_first 未区分 fact / declared_standard / future_intent
• 高风险领域规则缺失，或关键规则不可验证
• 工作流钩子缺失，导致下游无法判断是否需要重审
• 明显把 feature-specific 设计细节写进 Guardrails

P1 典型场景：

• 适用范围 / 非范围不清
• 例外流程、复审周期、更新触发条件不完整
• 事实与标准冲突已出现，但只被“模糊带过”，没有明确 drift / 待决策结论
• 下游重审建议存在，但影响域不完整或阻塞级别不一致

P2 典型场景：

• 描述不够清晰
• 示例不足
• 变更摘要、影响说明不够好扫读

执行进度清单

执行时使用 TodoWrite 工具跟踪以下进度，完成一项后立即标记为 completed：

□ Phase 0：基线与动作识别
  □ 0.1 读取 Guardrails 文档或 no_change 摘要
  □ 0.2 识别本次动作类型与生成模式
  □ 0.3 AskUserQuestion 补齐范围/目标状态缺口
  □ 0.4 输出基线识别结果
□ Gate 1：触发判定与元信息
  □ 1.1 create/update/restructure/no_change 判定检查
  □ 1.2 元信息与范围检查
  □ 1.3 更新触发条件与复审周期检查
□ Gate 2：证据与事实标准
  □ 2.1 证据来源完整性检查
  □ 2.2 fact / declared_standard / future_intent 分层检查
  □ 2.3 drift / 待决策处理检查
□ Gate 3：规则质量与治理完整性
  □ 3.1 规则表完整性检查
  □ 3.2 项目级边界检查
  □ 3.3 例外流程与验证方式检查
□ Gate 4：工作流钩子与下游影响
  □ 4.1 受影响领域检查
  □ 4.2 下游重审清单检查
  □ 4.3 阻塞建议一致性检查
□ Gate 5：一致性与可落地性
  □ 5.1 与技术栈/现有规范/仓库事实冲突检查
  □ 5.2 可执行性与可验证性检查
□ Phase 6：输出结果
  □ 6.1 汇总问题清单
  □ 6.2 输出审查报告或准出证书

工作流程

Phase 0：基线与动作识别

1. 读取 Guardrails 文档；如果审的是 no_change 结论，则读取该结论摘要和证据说明 2. 识别本次动作类型：

• create_baseline
• update_impacted_domains
• restructure
• no_change

3. 如有正文变更，继续识别生成模式：

• interview_first
• repository_scan_first

4. 若适用范围、目标状态、证据边界不清，使用 references/askuser-templates.md 5. 输出「基线识别结果」

Gate 1：触发判定与元信息

目标：确认这次 Guardrails 变更本身是合理的项目级动作。

检查项：

• 动作类型是否与证据一致
• no_change 是否给出了充分理由，而不是跳过该改的治理更新
• 元信息是否完整：版本、状态、Owner、生效日期、复审周期、动作类型、触发原因、适用范围
• 范围 / 非范围是否清晰
• 更新触发条件、复审周期、变更记录是否存在

判定：

• 动作类型缺失或明显误判 → P0
• 范围/非范围缺失 → P0
• 更新触发条件或复审周期缺失 → P1

Gate 2：证据与事实标准

目标：确认这份 Guardrails 是被证据支撑的，而不是把现状、口头意图和标准混在一起。

检查项：

• 是否列出了关键证据来源
• 若为 repository_scan_first，是否明确区分：
• fact
• declared_standard
• future_intent
• 事实与标准冲突时，是否明确标成：
• drift
• 待决策
• 维持目标状态
• 按现状更新
• 关键规则候选是否有足够证据支撑，而不是局部实现或技术债

判定：

• repository_scan_first 未做证据分层 → P0
• 冲突存在但未给出处理结论 → P1
• 来源不充分但还能理解主要意图 → P2

Gate 3：规则质量与治理完整性

目标：确认规则本身可执行、可审查、没有越界。

检查项：

• 每条规则是否包含：Rule ID、Level、Rule、Rationale、Applies To、Verification、Owner、Source
• Must / Should / Nice 分级是否清晰
• 是否明确默认选择、允许范围、禁止项
• 是否有例外流程：申请人、审批人、有效期、记录位置、到期复审方式
• 是否把 feature-specific 设计、函数/DDL/具体实现塞进 Guardrails
• 若采用分域模式，index 是否只承载总则与钩子，分域文档负责具体规则

判定：

• 关键规则缺 Verification / Owner / Source → P0
• 例外流程缺失或不可执行 → P1
• 发现越界实现细节 → P2；若大量越界并影响定位，则升级 P1

Gate 4：工作流钩子与下游影响

目标：确认这份 Guardrails 能真正被 api/hld/lld/runbook 等下游消费。

检查项：

• 是否明确本次变更影响了哪些领域
• 是否明确哪些下游文档/技能需要重审
• 阻塞建议是否清晰：
• block_before_design
• review_before_merge
• sync_next_cycle
• 工作流钩子是否与 references/workflow-hooks.md 一致
• 是否遗漏关键下游：api-writer/reviewer、hld-writer/reviewer、lld-writer/reviewer、runbook-writer

判定：

• 高风险领域变化却没有下游重审建议 → P0
• 影响域不完整或阻塞级别不一致 → P1
• 只是表达不够清晰 → P2

Gate 5：一致性与可落地性

目标：确认规则与仓库现实、项目目标和技术栈之间没有不可调和的断裂。

检查项：

• 是否与既有技术栈、批准标准、稳定仓库事实冲突
• 若冲突存在，是否已明确：
• 保持现有标准，并要求下游对齐
• 按现状更新标准
• 暂列待决策
• 规则是否可通过 lint / review / CI / runbook / 运行检查验证
• 是否具备足够清晰的 Owner 和执行责任

判定：

• 关键规则与项目现实冲突且无处理路径 → P0
• 有冲突但处理路径不完整 → P1
• 规则可验证性偏弱但不影响主结论 → P2

Phase 6：输出结果

输出格式见 references/report-templates.md。

• 不通过：输出审查报告，按 Gate 汇总问题与修复建议
• 通过：输出准出证书，确认它可作为新的项目治理基线被下游消费

AskUserQuestion 规则

• 只问 reviewer 无法从文档和仓库事实判定的关键问题
• 优先确认：范围、目标状态、事实冲突、阻塞级别
• 如果 no_change 理由薄弱，必须追问“为什么不更新 Guardrails”
• 模板见 references/askuser-templates.md

禁止行为

• 不要替作者补写规则正文
• 不要把“事实标准冲突”含糊带过
• 不要只审规则表，不审触发原因和下游钩子
• 不要把 reviewer 退化成格式检查器
• 不要因为是治理文档就放松准出门槛

参考文档

AskUserQuestion 模板

本文档定义 guardrails-reviewer 审查过程中需要向用户确认的问题模板。

---

适用范围确认

触发时机：Phase 0 - 无法确定 Guardrails 适用于哪个系统/团队/仓库

question: "请确认这份 Guardrails 的适用范围"
header: "适用范围"
multiSelect: false
options:
  - label: "文档已写明"
    description: "直接按文档范围评审"
  - label: "需要补充范围"
    description: "请补充适用系统/团队/仓库/运行环境"
  - label: "其实只适用于当前功能"
    description: "这说明它可能不该写成 Guardrails"

---

动作类型确认

触发时机：Phase 0 - 无法确定本次是 create/update/restructure/no_change

question: "请确认这次 Guardrails 变更的动作类型"
header: "动作类型"
multiSelect: false
options:
  - label: "首次建立基线"
    description: "对应 create_baseline"
  - label: "只更新受影响领域"
    description: "对应 update_impacted_domains"
  - label: "重构治理结构"
    description: "对应 restructure"
  - label: "其实不该改 Guardrails"
    description: "对应 no_change，应回到 HLD/LLD/ADR"

---

事实冲突裁决

触发时机：Gate 2 - 仓库事实与声明性标准冲突，无法判断目标状态

question: "检测到仓库事实与现有标准冲突，应按哪种方式评审？"
header: "事实冲突"
multiSelect: false
options:
  - label: "按当前批准标准"
    description: "实现现状属于漂移，Guardrails 应维持目标状态"
  - label: "按仓库稳定事实"
    description: "现有标准已过期，Guardrails 应更新为现状"
  - label: "记录为待决策"
    description: "目前无法判断，先要求显式决策"

---

下游阻塞级别确认

触发时机：Gate 4 - 无法确定 Guardrails 更新是否应阻塞下游设计/发布

question: "这次 Guardrails 变更对下游的默认阻塞级别应是什么？"
header: "阻塞级别"
multiSelect: false
options:
  - label: "先更新再继续设计"
    description: "对应 block_before_design"
  - label: "合并前重审即可"
    description: "对应 review_before_merge"
  - label: "下个周期对齐"
    description: "对应 sync_next_cycle"

Review Report Template

Baseline identification results

• Guardrails path:
• Action types: create_baseline / update_impacted_domains / restructure / no_change
• Generate modes: interview_first / repository_scan_first / N/A
• Scope of application:
• Trigger reason:
• Conclusion: Can continue / P0 blocked

---

Review report (failed)

• Conclusion: Failed (P0: x, P1: y, P2: z)
• Guardrails version:
• Action type:
• Build mode:
• Review Gate: Gate1/Gate2/Gate3/Gate4/Gate5

De facto standards and conflict summary

• Key facts:
• Declarative standards:
• Conflict/drift:
• Adequacy of treatment:

Summary of Downstream Impacts

• Affected areas:
• Downstream documents/skills that need to be reviewed:
• Blocking suggestions:

---

Certificate of approval (passed)

• Conclusion: Passed (P0:0, P1:0, P2≤2)
• Guardrails version:
• Action type:
• Build mode:
• Reviewer：

Confirmation of departure

• Trigger judgment established: Yes / No
• Factual criterion sufficient: Yes / No / N/A
• Rule enforceable: Yes / No
• Downstream workflow hooks complete: Yes/No
• Can be used as a project governance baseline for downstream consumption: Yes / No

Summary of Downstream Impacts

• Affected areas:
• Downstream documents/skills that need to be reviewed:
• Blocking suggestions:
• Residual P2:

审查报告模板

基线识别结果

• Guardrails 路径：
• 动作类型：create_baseline / update_impacted_domains / restructure / no_change
• 生成模式：interview_first / repository_scan_first / N/A
• 适用范围：
• 触发原因：
• 结论：可继续 / P0 阻断

---

审查报告（未通过）

• 结论：不通过（P0: x, P1: y, P2: z）
• Guardrails 版本：
• 动作类型：
• 生成模式：
• 审查 Gate：Gate1 / Gate2 / Gate3 / Gate4 / Gate5

事实标准与冲突摘要

• 关键事实：
• 声明性标准：
• 冲突 / drift：
• 处理是否充分：

下游影响摘要

• 受影响领域：
• 需要重审的下游文档 / 技能：
• 阻塞建议：

---

准出证书（通过）

• 结论：通过（P0:0, P1:0, P2≤2）
• Guardrails 版本：
• 动作类型：
• 生成模式：
• Reviewer：

准出确认

• 触发判定成立：是 / 否
• 事实标准充分：是 / 否 / N/A
• 规则可执行：是 / 否
• 下游工作流钩子完整：是 / 否
• 可作为项目治理基线被下游消费：是 / 否

下游影响摘要

• 受影响领域：
• 需要重审的下游文档 / 技能：
• 阻塞建议：
• 残留 P2：

Guardrails 审查清单

Gate 1：触发判定与元信息

• 已明确本次是 create_baseline、update_impacted_domains、restructure 或 no_change
• 若为 no_change，已给出充分理由，且没有遗漏本应上升为项目级规则的变化
• 元信息完整：版本、状态、Owner、生效日期、复审周期、动作类型、触发原因、适用范围
• 范围与非范围明确
• 变更记录存在

Gate 2：证据与事实标准

• 关键证据来源明确
• 若为 repository_scan_first，已区分 fact、declared_standard、future_intent
• 事实与标准冲突时，已明确标记为 drift / 待决策 / 按现状更新 / 维持目标状态
• 没有把局部实现、技术债、漂移现状直接升格为 Guardrail

Gate 3：规则质量与治理完整性

• 每条关键规则都有 Rule ID / Level / Rule / Rationale / Applies To / Verification / Owner / Source
• Must / Should / Nice 分级清晰
• 默认选择、允许范围、禁止项明确
• 例外流程完整可执行
• 未混入 feature-specific 设计细节
• 分域模式下，index 与领域文档职责清楚

Gate 4：工作流钩子与下游影响

• 已明确本次变更影响了哪些领域
• 已列出需要重审的下游文档/技能
• 阻塞建议清晰且一致：block_before_design / review_before_merge / sync_next_cycle
• API/HLD/LLD/Runbook 等关键下游未遗漏
• 与 workflow-hooks.md 的映射口径一致

Gate 5：一致性与可落地性

• 与现有技术栈、批准标准、稳定仓库事实不冲突
• 若存在冲突，已给出明确处理路径
• 规则能通过 lint / review / CI / 运行检查等方式验证
• Owner 与执行责任清楚