review-policy-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

review-policy-builder

审查策略构建器

Create and maintain the project-specific review policy consumed by

agentic-review

This skill is interview-first and evidence-grounded:

derive what is already true from repo docs and ADRs
mine high-confidence implementation conventions from the repository
capture missing project/domain constraints from the user
write structured policy artifacts in
```
<docs-dir>/review/policies/
```
define review audit governance in
```
POLICY_INDEX.md
```
for specialist attestation and completion rules

Read references/policy-contract.md before writing policy files. It is the canonical schema and includes onion/clean-architecture templates.

创建并维护供

agentic-review

使用的项目特定审查策略。

此技能以访谈为先导、以证据为基础：

从仓库文档和ADR中提取已有的规则
从仓库中挖掘高可信度的实现约定
收集用户提供的项目/领域缺失约束
在
```
<docs-dir>/review/policies/
```
下编写结构化策略工件
在
```
POLICY_INDEX.md
```
中定义审查审计治理规则，用于专业人员认证和完成规则

编写策略文件前，请阅读references/policy-contract.md。这是标准规范，包含洋葱/整洁架构模板。

Phase 1 — Verify prerequisites and locate

<docs-dir>

阶段1 — 验证前提条件并定位

<docs-dir>

This skill runs after

setup-agentic-repository

Read root
```
AGENTS.md
```
.
Discover
```
<docs-dir>
```
from
```
AGENTS.md
```
contract paths.
Fallback: find
```
AGENTS_CONTEXT.md
```
and use its parent directory as
```
<docs-dir>
```
.

Confirm required files:

```
AGENTS.md
```
```
<docs-dir>/ENGINEERING.md
```
```
<docs-dir>/AGENTS_CONTEXT.md
```
at least one
```
CONTEXT.md
```

Optional but strongly preferred:

```
<docs-dir>/CONTEXT-MAP.md
```
```
<docs-dir>/adr/*.md
```

If required files are missing, fail fast with actionable remediation: run/fix

setup-agentic-repository

first.

此技能需在

setup-agentic-repository

之后运行。

读取根目录下的
```
AGENTS.md
```
文件。
从
```
AGENTS.md
```
的契约路径中发现
```
<docs-dir>
```
。
备选方案：找到
```
AGENTS_CONTEXT.md
```
并将其父目录作为
```
<docs-dir>
```
。

确认所需文件：

```
AGENTS.md
```
```
<docs-dir>/ENGINEERING.md
```
```
<docs-dir>/AGENTS_CONTEXT.md
```
至少一个
```
CONTEXT.md
```

可选但强烈推荐：

```
<docs-dir>/CONTEXT-MAP.md
```
```
<docs-dir>/adr/*.md
```

如果缺少所需文件，快速失败并提供可执行的补救措施：先运行/修复

setup-agentic-repository

。

Phase 2 — Load baseline truth before asking questions

阶段2 — 在提问前加载基准规则

Read these sources first, then summarize extracted constraints:

```
AGENTS.md
```
for global workflow and non-negotiables
```
<docs-dir>/ENGINEERING.md
```
for coding/testing/quality standards
```
<docs-dir>/CONTEXT-MAP.md
```
(if present) and relevant
```
CONTEXT.md
```
files for module boundaries, public surfaces, invariants, and dependency direction hints
```
<docs-dir>/adr/*.md
```
for architecture decisions and constraints

Extract candidate rules from those files into a working list tagged

source: derived

source: adr

Do not ask the user to restate anything already explicit in these files.

先读取以下来源，然后总结提取的约束：

```
AGENTS.md
```
：全局工作流和不可协商规则
```
<docs-dir>/ENGINEERING.md
```
：编码/测试/质量标准
```
<docs-dir>/CONTEXT-MAP.md
```
（如果存在）及相关
```
CONTEXT.md
```
文件：模块边界、公共接口、不变量和依赖方向提示
```
<docs-dir>/adr/*.md
```
：架构决策和约束

从这些文件中提取候选规则，放入标记为

source: derived

或

source: adr

的工作列表。

不要要求用户重述这些文件中已明确说明的内容。

Phase 3 — Mine repository convention candidates (inheritance v1)

阶段3 — 挖掘仓库约定候选（继承规则v1）

Before interviewing, mine code-level conventions that can become automatable review checks.

Scope (v1):

inheritance conventions only (
```
check_type: inheritance_suffix
```
)

Mining workflow:

Scan repository code (prioritize module-owned subtrees from
```
CONTEXT-MAP.md
```
/
```
CONTEXT.md
```
) for class declarations and inheritance/base-type relationships.
Detect suffix-based inheritance candidates (for example
```
*Controller
```
extending
```
*MainController
```
,
```
*Service
```
extending
```
*MainService
```
).
Build candidate evidence:
- class suffix
- expected base suffix
- sample count
- adoption ratio (
```
matching_samples / total_samples
```
  )
- representative file+line evidence for matching and violating samples

Candidate promotion defaults:

```
min_samples = 4
```
```
min_adoption_ratio = 0.85
```

Classify candidates:
- ```
promoted-candidate
```
  : meets both thresholds
- ```
exploratory-candidate
```
  : below threshold (show to user only when useful)

Scoping defaults:

module-first by subtree ownership
if the same candidate is confirmed across multiple modules, promote to a global rule

Never persist mined conventions automatically. They must be explicitly confirmed in the interview.

在访谈前，挖掘可转化为自动化审查检查的代码级约定。

范围（v1）：

仅继承约定（
```
check_type: inheritance_suffix
```
）

挖掘流程：

扫描仓库代码（优先处理
```
CONTEXT-MAP.md
```
/
```
CONTEXT.md
```
中定义的模块所属子树），查找类声明和继承/基类关系。
检测基于后缀的继承候选（例如
```
*Controller
```
继承自
```
*MainController
```
，
```
*Service
```
继承自
```
*MainService
```
）。
构建候选证据：
- 类后缀
- 预期基类后缀
- 样本数量
- 采用率（
```
匹配样本数 / 总样本数
```
  ）
- 匹配和违规样本的代表性文件+行号证据

候选晋升默认阈值：

```
min_samples = 4
```
```
min_adoption_ratio = 0.85
```

候选分类：
- ```
promoted-candidate
```
  ：满足两个阈值
- ```
exploratory-candidate
```
  ：未达到阈值（仅在有用时展示给用户）

范围默认规则：

按子树所属模块优先处理
如果同一候选在多个模块中得到确认，则晋升为全局规则

不要自动持久化挖掘到的约定。必须在访谈中得到明确确认。

Phase 4 — Structured interview for missing policy

阶段4 — 针对缺失策略的结构化访谈

Run a focused interview to capture project-specific review checks not present in baseline docs. Use

AskUserQuestion

and resolve one decision at a time.

Target gaps:

architecture integrity rules (onion/clean/hexagonal)
allowed dependency direction and forbidden layer crossings
call-flow restrictions (for example controller -> application -> domain -> infrastructure)
inherited code conventions discovered in Phase 3 (candidate confirmation, severity, exceptions)
module exceptions (allowed boundary breaks and justification)
transaction/data integrity rules
security/business-risk hotspots that deserve stricter scrutiny

Rules for the interview:

propose concrete options with recommended defaults
for each promoted convention candidate, request explicit confirm/reject
when confirmed, capture severity and explicit allowed exceptions
capture explicit exceptions and evidence requirements
resolve ambiguities immediately; do not leave vague prose
when user input conflicts with ADRs, mark conflict as
```
needs decision
```
in output artifacts

开展聚焦访谈，收集基准文档中未涵盖的项目特定审查检查规则。使用

AskUserQuestion

，每次解决一个决策。

目标缺口：

架构完整性规则（洋葱/整洁/六边形架构）
允许的依赖方向和禁止的层交叉
调用流限制（例如controller -> application -> domain -> infrastructure）
阶段3中发现的继承代码约定（候选确认、严重程度、例外情况）
模块例外（允许的边界突破及理由）
事务/数据完整性规则
需要更严格审查的安全/业务风险热点

访谈规则：

提出带有推荐默认值的具体选项
对每个晋升的约定候选，请求明确的确认/拒绝
确认后，记录严重程度和明确允许的例外情况
记录明确的例外情况和证据要求
立即解决歧义；不要留下模糊描述
当用户输入与ADR冲突时，在输出工件中标记为
```
needs decision
```

Phase 5 — Write policy artifacts under

<docs-dir>/review/policies/

阶段5 — 在

<docs-dir>/review/policies/

下编写策略工件

Produce this contract:

```
global-policy.md
```
— cross-project rules and global constraints
```
module-<slug>.md
```
— one per module/context
- multi-context: derive
```
<slug>
```
  from context rows in
```
CONTEXT-MAP.md
```
- single-context: write one module file for the single context
```
POLICY_INDEX.md
```
— index and routing map:
- module/context -> policy file
- primary subtree ownership
- policy version/updated metadata
- review audit contract for
```
agentic-review
```

Use the schema from

references/policy-contract.md

. Each rule must include required metadata fields:

```
id
```
```
title
```
```
scope
```
(
```
global
```
or
```
module:<slug>
```
)
```
severity
```
(
```
critical|high|medium|low
```
)
```
intent
```
```
check_logic
```
```
evidence_expectation
```
```
allowed_exceptions
```
```
source
```
(
```
derived|user-specified|adr
```
)
```
related_adr
```
(optional)

Automation metadata (optional, recommended for deterministic checks):

Add machine-usable
```
automation
```
metadata for confirmed inheritance conventions.
For inheritance checks, set:
- ```
check_type: inheritance_suffix
```
- ```
apply_scope: changed-files
```
  (default)
- selector and expectation fields defined by the policy contract

Convention rule scoping:

default to module policy files (
```
module-<slug>.md
```
)
promote to
```
global-policy.md
```
only when the same convention is confirmed across modules
keep module-specific exceptions local unless explicitly approved as global

POLICY_INDEX.md

must include

Review Audit Contract

with:

```
audit_contract_version
```
```
completion_mode: fail-closed
```

required attestation fields:

```
specialist_slug
```
```
specialist_type
```
```
assigned_scope
```
```
status
```
```
signed_at
```
```
attestation_text
```
```
output_artifact_path
```

required specialist categories:
- module specialists always required
- cross-cut specialists required when routed by file semantics
transparency mode:
- ```
summary + artifact links
```

生成以下契约：

```
global-policy.md
```
— 跨项目规则和全局约束
```
module-<slug>.md
```
— 每个模块/上下文对应一个文件
- 多上下文：从
```
CONTEXT-MAP.md
```
  的上下文行中派生
```
<slug>
```
- 单上下文：为单个上下文编写一个模块文件
```
POLICY_INDEX.md
```
— 索引和路由映射：
- 模块/上下文 -> 策略文件
- 主要子树所属权
- 策略版本/更新元数据
- 供
```
agentic-review
```
  使用的审查审计契约

使用

references/policy-contract.md

中的规范。每个规则必须包含必填元数据字段：

```
id
```
```
title
```
```
scope
```
（
```
global
```
或
```
module:<slug>
```
）
```
severity
```
（
```
critical|high|medium|low
```
）
```
intent
```
```
check_logic
```
```
evidence_expectation
```
```
allowed_exceptions
```
```
source
```
（
```
derived|user-specified|adr
```
）
```
related_adr
```
（可选）

自动化元数据（可选，推荐用于确定性检查）：

为已确认的继承约定添加机器可读取的
```
automation
```
元数据。
对于继承检查，设置：
- ```
check_type: inheritance_suffix
```
- ```
apply_scope: changed-files
```
  （默认值）
- 策略契约中定义的选择器和预期字段

约定规则范围：

默认放入模块策略文件（
```
module-<slug>.md
```
）
仅当同一约定在多个模块中得到确认时，才晋升到
```
global-policy.md
```
模块特定例外情况保持本地化，除非明确批准为全局规则

POLICY_INDEX.md

必须包含

Review Audit Contract

部分，内容包括：

```
audit_contract_version
```
```
completion_mode: fail-closed
```

必填认证字段：

```
specialist_slug
```
```
specialist_type
```
```
assigned_scope
```
```
status
```
```
signed_at
```
```
attestation_text
```
```
output_artifact_path
```

必填专业人员类别：
- 始终需要模块专业人员
- 当按文件语义路由时，需要跨领域专业人员
透明模式：
- ```
summary + artifact links
```

Phase 6 — Update/merge behavior on reruns

阶段6 — 重新运行时的更新/合并行为

If policy files already exist:

merge/update in place; do not overwrite blindly
preserve stable
```
id
```
values for unchanged rules
update metadata and content for modified rules
mark obsolete rules as deprecated; do not silently delete history
keep
```
POLICY_INDEX.md
```
synchronized with current module list

Conflict handling:

if a new/updated rule contradicts ADR constraints, mark it as
```
needs decision
```
and document the conflict in both impacted policy file and
```
POLICY_INDEX.md
```

如果策略文件已存在：

原地合并/更新；不要盲目覆盖
保留未更改规则的稳定
```
id
```
值
更新修改后规则的元数据和内容
将过时规则标记为已弃用；不要静默删除历史记录
保持
```
POLICY_INDEX.md
```
与当前模块列表同步

冲突处理：

如果新/更新的规则与ADR约束冲突，将其标记为
```
needs decision
```
，并在受影响的策略文件和
```
POLICY_INDEX.md
```
中记录冲突

Phase 7 — Integration contract for

agentic-review

阶段7 — 与

agentic-review

的集成契约

This skill must produce artifacts that

agentic-review

can consume deterministically:

policy location:
```
<docs-dir>/review/policies/
```

expected files:

```
POLICY_INDEX.md
```
```
global-policy.md
```
```
module-<slug>.md
```

each rule has machine-usable metadata fields (no prose-only rules)
inheritance convention rules that should run automatically include
```
automation.check_type: inheritance_suffix
```
```
POLICY_INDEX.md
```
includes a machine-readable
```
Review Audit Contract
```
section

Document in

POLICY_INDEX.md

which modules have policy coverage
which rules are global vs module-scoped
which rules are automatable (
```
check_type
```
, scope, and owning policy file)
review audit contract values (
```
audit_contract_version
```
,
```
completion_mode
```
, required attestation fields, required specialist categories, transparency mode)
any
```
needs decision
```
conflicts unresolved at authoring time

此技能必须生成

agentic-review

可确定性读取的工件：

策略位置：
```
<docs-dir>/review/policies/
```

预期文件：

```
POLICY_INDEX.md
```
```
global-policy.md
```
```
module-<slug>.md
```

每个规则都有机器可读取的元数据字段（无纯文本规则）
应自动运行的继承约定规则包含
```
automation.check_type: inheritance_suffix
```
```
POLICY_INDEX.md
```
包含机器可读的
```
Review Audit Contract
```
部分

在

POLICY_INDEX.md

中记录：

哪些模块有策略覆盖
哪些规则是全局规则 vs 模块范围规则
哪些规则可自动化（
```
check_type
```
、范围和所属策略文件）
审查审计契约值（
```
audit_contract_version
```
、
```
completion_mode
```
、必填认证字段、必填专业人员类别、透明模式）
编写时未解决的
```
needs decision
```
冲突

Phase 8 — Report back

阶段8 — 反馈报告

Tell the user:

which files were created/updated
which rules were derived vs user-specified
which mined convention candidates were confirmed, rejected, or deferred
which review audit contract values were set in
```
POLICY_INDEX.md
```
unresolved
```
needs decision
```
conflicts
which modules still need policy refinement
artifact hygiene outcome (what
```
.gitignore
```
entries were added, or that no changes were applied)

At the end of every run, add an artifact-hygiene decision step before finishing:

Explain that
```
agentic-review
```
produces multiple generated artifacts under
```
<docs-dir>/review/
```
:
- ```
review-plan-*.md
```
  (plan)
- ```
review-plan-*.diffs/
```
  (full scoped diffs)
- ```
review-result-*.specialists/
```
  (raw specialist outputs)
- ```
review-result-*.md
```
  (human-readable summary)
- ```
review-manifest-*.json
```
  (machine-readable manifest)
Explain the tradeoff explicitly:
- keeping these files tracked preserves review/audit history
- ignoring some or all reduces repository noise
Ask the user to choose one ignore strategy with
```
AskUserQuestion
```
:

yaml

questions:
  - question: "Would you like me to update `.gitignore` for generated `agentic-review` artifacts?"
    header: "Review Artifacts"
    multiSelect: false
    options:
      - label: "Ignore all review artifacts (Recommended)"
        description: "Add ignore patterns for plans, diff directories, specialist outputs, result summaries, and manifests."
      - label: "Ignore diff files only"
        description: "Ignore only `review-plan-*.diffs/` directories and keep other review artifacts tracked."
      - label: "Keep review artifacts tracked"
        description: "Do not modify `.gitignore`."

Apply deterministic mapping to root

.gitignore

Ignore all review artifacts (Recommended)

```
<docs-dir>/review/review-plan-*.md
```
```
<docs-dir>/review/review-plan-*.diffs/
```

<docs-dir>/review/review-result-*.specialists/

```
<docs-dir>/review/review-result-*.md
```

<docs-dir>/review/review-manifest-*.json

Ignore diff files only

```
<docs-dir>/review/review-plan-*.diffs/
```

```
Keep review artifacts tracked
```
:
- no
```
.gitignore
```
  changes

Idempotency requirements:

never add duplicate
```
.gitignore
```
lines
preserve existing
```
.gitignore
```
content order except for appended new lines when needed
if all required lines already exist for the chosen option, report
```
no-op
```
instead of rewriting

Do not commit changes. The user reviews policy artifacts first.

告知用户：

创建/更新了哪些文件
哪些规则是派生的 vs 用户指定的
哪些挖掘的约定候选被确认、拒绝或推迟
```
POLICY_INDEX.md
```
中设置了哪些审查审计契约值
未解决的
```
needs decision
```
冲突
哪些模块仍需策略优化
工件清理结果（添加了哪些
```
.gitignore
```
条目，或未应用任何更改）

在每次运行结束时，完成前添加一个工件清理决策步骤：

说明
```
agentic-review
```
会在
```
<docs-dir>/review/
```
下生成多个工件：
- ```
review-plan-*.md
```
  （审查计划）
- ```
review-plan-*.diffs/
```
  （完整范围差异）
- ```
review-result-*.specialists/
```
  （原始专业人员输出）
- ```
review-result-*.md
```
  （人类可读摘要）
- ```
review-manifest-*.json
```
  （机器可读清单）
明确解释权衡：
- 跟踪这些文件可保留审查/审计历史
- 忽略部分或全部文件可减少仓库冗余
使用
```
AskUserQuestion
```
让用户选择一种忽略策略：

yaml

questions:
  - question: "Would you like me to update `.gitignore` for generated `agentic-review` artifacts?"
    header: "Review Artifacts"
    multiSelect: false
    options:
      - label: "Ignore all review artifacts (Recommended)"
        description: "Add ignore patterns for plans, diff directories, specialist outputs, result summaries, and manifests."
      - label: "Ignore diff files only"
        description: "Ignore only `review-plan-*.diffs/` directories and keep other review artifacts tracked."
      - label: "Keep review artifacts tracked"
        description: "Do not modify `.gitignore`."

将选择映射到根目录

.gitignore

：

Ignore all review artifacts (Recommended)

：

```
<docs-dir>/review/review-plan-*.md
```
```
<docs-dir>/review/review-plan-*.diffs/
```

<docs-dir>/review/review-result-*.specialists/

```
<docs-dir>/review/review-result-*.md
```

<docs-dir>/review/review-manifest-*.json

Ignore diff files only

：

```
<docs-dir>/review/review-plan-*.diffs/
```

```
Keep review artifacts tracked
```
：
- 不修改
```
.gitignore
```

幂等性要求：

绝不添加重复的
```
.gitignore
```
行
保留现有
```
.gitignore
```
内容顺序，仅在需要时追加新行
如果所选选项的所有必填行已存在，则报告
```
no-op
```
而非重写

不要提交更改。用户需先审查策略工件。

review-policy-builder

Original

Translation

review-policy-builder

审查策略构建器

Phase 1 — Verify prerequisites and locate
`<docs-dir>`

阶段1 — 验证前提条件并定位
`<docs-dir>`

Phase 2 — Load baseline truth before asking questions

阶段2 — 在提问前加载基准规则

Phase 3 — Mine repository convention candidates (inheritance v1)

阶段3 — 挖掘仓库约定候选（继承规则v1）

Phase 4 — Structured interview for missing policy

阶段4 — 针对缺失策略的结构化访谈

Phase 5 — Write policy artifacts under
`<docs-dir>/review/policies/`

阶段5 — 在
`<docs-dir>/review/policies/`
下编写策略工件

Phase 6 — Update/merge behavior on reruns

阶段6 — 重新运行时的更新/合并行为

Phase 7 — Integration contract for
`agentic-review`

阶段7 — 与
`agentic-review`
的集成契约

Phase 8 — Report back

阶段8 — 反馈报告

review-policy-builder

Original

Translation

review-policy-builder

审查策略构建器

Phase 1 — Verify prerequisites and locate <docs-dir>

阶段1 — 验证前提条件并定位<docs-dir>

Phase 2 — Load baseline truth before asking questions

阶段2 — 在提问前加载基准规则

Phase 3 — Mine repository convention candidates (inheritance v1)

阶段3 — 挖掘仓库约定候选（继承规则v1）

Phase 4 — Structured interview for missing policy

阶段4 — 针对缺失策略的结构化访谈

Phase 5 — Write policy artifacts under <docs-dir>/review/policies/

阶段5 — 在<docs-dir>/review/policies/下编写策略工件

Phase 6 — Update/merge behavior on reruns

阶段6 — 重新运行时的更新/合并行为

Phase 7 — Integration contract for agentic-review

阶段7 — 与agentic-review的集成契约

Phase 8 — Report back

阶段8 — 反馈报告

Phase 1 — Verify prerequisites and locate
`<docs-dir>`

阶段1 — 验证前提条件并定位
`<docs-dir>`

Phase 5 — Write policy artifacts under
`<docs-dir>/review/policies/`

阶段5 — 在
`<docs-dir>/review/policies/`
下编写策略工件

Phase 7 — Integration contract for
`agentic-review`

阶段7 — 与
`agentic-review`
的集成契约