gh-address-cr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

gh-address-cr

Use this skill as the PR review orchestrator. It owns session state, intake routing, and the final gate.

将此skill用作PR评审编排器。它负责会话状态、输入路由以及最终校验门。

Usage

使用方法

text

/gh-address-cr review <owner/repo> <pr_number>
/gh-address-cr threads <owner/repo> <pr_number>
/gh-address-cr findings <owner/repo> <pr_number> --input <path>|-
/gh-address-cr adapter <owner/repo> <pr_number> <adapter_cmd...>

text

/gh-address-cr review <owner/repo> <pr_number>
/gh-address-cr threads <owner/repo> <pr_number>
/gh-address-cr findings <owner/repo> <pr_number> --input <path>|-
/gh-address-cr adapter <owner/repo> <pr_number> <adapter_cmd...>

Packaging Scope

打包范围

This file is part of the packaged

gh-address-cr

skill. All paths in this document are relative to the installed skill root.

```
scripts/...
```
means files inside this packaged skill
```
references/...
```
means skill-owned reference docs
```
agents/openai.yaml
```
is an assistant-specific hint file inside the skill

A surrounding source repository may also contain repo-level tests, CI, and release metadata, but those are outside the packaged skill payload.

本文件是打包后的

gh-address-cr

skill的一部分。本文档中的所有路径均相对于已安装的skill根目录。

```
scripts/...
```
指此打包skill内的文件
```
references/...
```
指skill所属的参考文档
```
agents/openai.yaml
```
是skill内的一个助手特定提示文件

外部的源仓库可能还包含仓库级别的测试、CI和发布元数据，但这些不属于打包后的skill payload。

Agent Execution Ladder

Agent执行阶梯

Read this skill in this order when you are an AI agent:

Start from the public main entrypoint:
```
review <owner/repo> <pr_number>
```
.

review

returns

WAITING_FOR_EXTERNAL_REVIEW

, fill the handoff files in the PR workspace:

```
producer-request.md
```
```
incoming-findings.json
```
```
incoming-findings.md
```

Rerun the same
```
review
```
command. It will auto-consume findings JSON or fixed
```
finding
```
blocks and continue orchestration.
If
```
review
```
returns
```
BLOCKED
```
, inspect the loop request artifact, apply
```
fix
```
,
```
clarify
```
, or
```
defer
```
, then rerun the same
```
review
```
command.
Use
```
threads
```
,
```
findings
```
,
```
adapter
```
, and
```
review-to-findings
```
only as advanced/internal integration surfaces.

Fail-fast rules:

```
review
```
is the only public main entrypoint.
```
review
```
does not bind to any one review skill or tool name.
If findings are absent,
```
review
```
returns
```
WAITING_FOR_EXTERNAL_REVIEW
```
and writes a standard producer handoff request instead of waiting on
```
stdin
```
.
External review producer output must be findings JSON or fixed
```
finding
```
blocks.
```
review-to-findings
```
does not accept arbitrary Markdown. It only accepts the fixed
```
finding
```
block format.
```
review
```
,
```
threads
```
, and
```
adapter
```
require
```
gh
```
on
```
PATH
```
and fail immediately when it is missing.
The high-level CLI commands are the only agent-safe public surface. Treat low-level scripts as internal implementation details.

Important:

```
review
```
is the default end-to-end orchestrator and the public main entrypoint.
```
review
```
manages session state, external review handoff, GitHub threads, and final-gate.
```
threads
```
,
```
findings
```
,
```
adapter
```
, and
```
review-to-findings
```
are advanced/internal entrypoints for explicit integrations.
```
review-to-findings
```
is only a converter. It is not a review engine and it is not a general Markdown parser.

Recommended high-level entrypoints:

```
review
```
- public main entrypoint
- generates a standard producer handoff when findings are absent
- handles both local findings and GitHub review threads in one run
```
threads
```
- advanced/internal: GitHub review threads only
```
findings
```
- advanced/internal: existing findings JSON only
- handles local findings only; it does not process GitHub review threads
```
adapter
```
- advanced/internal: adapter-produced findings plus PR orchestration
```
review-to-findings
```
- advanced/internal: fixed-format finding blocks to findings JSON

Examples:

text

$gh-address-cr review <PR_URL>
$gh-address-cr threads <PR_URL>
$gh-address-cr findings <PR_URL> --input findings.json
$gh-address-cr findings <PR_URL> --input - --sync
$gh-address-cr adapter <PR_URL> <adapter_cmd...>
$gh-address-cr review-to-findings <owner/repo> <pr_number> --input -

Minimal valid

review-to-findings

input:

text

```finding
title: Missing null guard
path: src/example.py
line: 12
body: Potential null dereference.
```

This converter rejects plain narrative Markdown review output.

AI Agent请按以下顺序使用此skill：

从公开主入口开始：
```
review <owner/repo> <pr_number>
```
。

如果

review

WAITING_FOR_EXTERNAL_REVIEW

，在PR工作区中填充交接文件：

```
producer-request.md
```
```
incoming-findings.json
```
```
incoming-findings.md
```

重新运行相同的
```
review
```
命令。它会自动读取结果JSON或已修复的
```
finding
```
块并继续编排。
如果
```
review
```
返回
```
BLOCKED
```
，检查循环请求工件，执行
```
fix
```
、
```
clarify
```
或
```
defer
```
操作，然后重新运行相同的
```
review
```
命令。
仅将
```
threads
```
、
```
findings
```
、
```
adapter
```
和
```
review-to-findings
```
用作高级/内部集成接口。

快速失败规则：

```
review
```
是唯一的公开主入口。
```
review
```
不绑定到任何特定的评审skill或工具名称。
如果结果缺失，
```
review
```
会返回
```
WAITING_FOR_EXTERNAL_REVIEW
```
并生成标准的生产者交接请求，而非等待
```
stdin
```
输入。
外部评审生产者的输出必须是结果JSON或已修复的
```
finding
```
块。
```
review-to-findings
```
不接受任意Markdown格式，仅接受固定的
```
finding
```
块格式。
```
review
```
、
```
threads
```
和
```
adapter
```
要求
```
gh
```
在
```
PATH
```
中，若缺失会立即失败。
高级CLI命令是唯一对Agent安全的公开接口，将低级脚本视为内部实现细节。

重要说明：

```
review
```
是默认的端到端编排器和公开主入口。
```
review
```
管理会话状态、外部评审交接、GitHub线程以及最终校验门。
```
threads
```
、
```
findings
```
、
```
adapter
```
和
```
review-to-findings
```
是用于显式集成的高级/内部入口。
```
review-to-findings
```
仅为转换器，不是评审引擎，也不是通用Markdown解析器。

推荐的高级入口：

```
review
```
- 公开主入口
- 当结果缺失时生成标准的生产者交接请求
- 一次运行即可处理本地结果和GitHub评审线程
```
threads
```
- 高级/内部：仅处理GitHub评审线程
```
findings
```
- 高级/内部：仅处理已有的结果JSON
- 仅处理本地结果，不处理GitHub评审线程
```
adapter
```
- 高级/内部：适配器生成的结果加上PR编排
```
review-to-findings
```
- 高级/内部：将固定格式的finding块转换为结果JSON

示例：

text

$gh-address-cr review <PR_URL>
$gh-address-cr threads <PR_URL>
$gh-address-cr findings <PR_URL> --input findings.json
$gh-address-cr findings <PR_URL> --input - --sync
$gh-address-cr adapter <PR_URL> <adapter_cmd...>
$gh-address-cr review-to-findings <owner/repo> <pr_number> --input -

review-to-findings

的最小有效输入：

text

```finding
title: Missing null guard
path: src/example.py
line: 12
body: Potential null dereference.
```

此转换器会拒绝普通叙述性的Markdown评审输出。

Machine Summary Contract

机器摘要约定

High-level commands emit structured JSON by default. Agents should consume these fields, not parse human prose:

```
status
```
```
repo
```
```
pr_number
```
```
item_id
```
```
item_kind
```
```
counts
```
```
artifact_path
```
```
reason_code
```
```
waiting_on
```
```
next_action
```
```
exit_code
```

reason_code

is the stable machine reason.

waiting_on

is the stable wait-state category.

counts.*

may be

null

in preflight wait/fail states before GitHub or session scans run.

高级命令默认输出结构化JSON。Agent应读取这些字段，而非解析自然语言：

```
status
```
```
repo
```
```
pr_number
```
```
item_id
```
```
item_kind
```
```
counts
```
```
artifact_path
```
```
reason_code
```
```
waiting_on
```
```
next_action
```
```
exit_code
```

reason_code

是稳定的机器原因，

waiting_on

是稳定的等待状态类别。在GitHub或会话扫描运行前的预检查等待/失败状态下，

counts.*

可能为

null

。

Advanced References

高级参考

Dispatch details:
```
references/mode-producer-matrix.md
```
Review triage checklist:
```
references/cr-triage-checklist.md
```
Optional OTel -> Worker -> Better Stack logging:
```
references/otel-worker-better-stack.md
```
Low-level scripts are implementation details, not the public agent surface.

Examples that require advanced dispatch details live in the reference docs instead of the first-read contract.

调度详情：
```
references/mode-producer-matrix.md
```
评审分类检查清单：
```
references/cr-triage-checklist.md
```
可选OTel -> Worker -> Better Stack日志：
```
references/otel-worker-better-stack.md
```
低级脚本是实现细节，不属于公开的Agent接口。

需要高级调度详情的示例请参考参考文档，而非首次阅读的约定内容。

Entry Contract

入口约定

Treat

SKILL.md

as the source of truth for using this skill.

Start from the high-level dispatcher:

python3 scripts/cli.py review <owner/repo> <pr_number>

python3 scripts/cli.py threads <owner/repo> <pr_number>

python3 scripts/cli.py findings <owner/repo> <pr_number> --input <path>|- [--sync]

python3 scripts/cli.py adapter <owner/repo> <pr_number> <adapter_cmd...>

Use
```
references/mode-producer-matrix.md
```
only for mode-specific dispatch details.
Do not rely on
```
agents/openai.yaml
```
for unique behavior; it is only a thin assistant-specific hint layer.

将

SKILL.md

视为使用此skill的权威来源。

从高级调度器开始：

python3 scripts/cli.py review <owner/repo> <pr_number>

python3 scripts/cli.py threads <owner/repo> <pr_number>

python3 scripts/cli.py findings <owner/repo> <pr_number> --input <path>|- [--sync]

python3 scripts/cli.py adapter <owner/repo> <pr_number> <adapter_cmd...>

仅在需要特定模式的调度详情时使用
```
references/mode-producer-matrix.md
```
。
不要依赖
```
agents/openai.yaml
```
实现独特行为，它仅为一层薄的助手特定提示层。

Capability Status

功能状态

These high-level paths are fully operational now:

```
review
```
```
threads
```
```
findings
```
```
adapter
```

The internal iteration and dispatch layers are implementation details and are not part of the public entrypoint surface.

Advanced producer and dispatch details live in:

```
references/mode-producer-matrix.md
```
```
references/cr-triage-checklist.md
```

以下高级路径目前已完全可用：

```
review
```
```
threads
```
```
findings
```
```
adapter
```

内部迭代和调度层是实现细节，不属于公开入口接口。

高级生产者和调度详情请参考：

```
references/mode-producer-matrix.md
```
```
references/cr-triage-checklist.md
```

Non-Negotiable Rule

不可协商规则

python3 scripts/cli.py final-gate

pass is mandatory before any completion statement.

Never output "done", "all resolved", "completed", or equivalent unless:
- ```
python3 scripts/cli.py final-gate <owner/repo> <pr_number>
```
  has just passed, and
- output includes
```
Verified: 0 Unresolved Threads found
```
  , and
- output includes
```
Verified: 0 Pending Reviews found
```
  , and
- session blocking item count is zero.
Use
```
audit_summary.md
```
or the machine-readable count lines printed by
```
final-gate
```
when run-scoped diagnostics are needed.
If gate fails, continue iteration; completion summary is forbidden.

在发布任何完成声明前，必须通过

python3 scripts/cli.py final-gate

校验。

除非满足以下所有条件，否则不得输出"完成"、"全部解决"、"已完成"或类似表述：
- 刚执行完
```
python3 scripts/cli.py final-gate <owner/repo> <pr_number>
```
  且通过
- 输出包含
```
Verified: 0 Unresolved Threads found
```
- 输出包含
```
Verified: 0 Pending Reviews found
```
- 会话阻塞项数量为0
当需要运行范围的诊断信息时，使用
```
audit_summary.md
```
或
```
final-gate
```
输出的机器可读计数行。
如果校验门失败，继续迭代；禁止发布完成摘要。

Core Rules

核心规则

Use the high-level task entrypoints first:

python3 scripts/cli.py review <owner/repo> <pr_number>

python3 scripts/cli.py threads <owner/repo> <pr_number>

python3 scripts/cli.py findings <owner/repo> <pr_number> --input <path>|-

python3 scripts/cli.py adapter <owner/repo> <pr_number> <adapter_cmd...>

Use the internal low-level dispatch only when the high-level entrypoints do not fit.
Process only unresolved GitHub threads and open local findings.
For GitHub review threads, reply and resolve are both mandatory.
Outdated /
```
STALE
```
GitHub threads are still unresolved until explicitly handled.
For local findings, terminal handling must include a note.
```
producer=code-review
```
must emit findings JSON before session handling starts.
Never declare completion before
```
python3 scripts/cli.py final-gate
```
passes.

优先使用高级任务入口：

python3 scripts/cli.py review <owner/repo> <pr_number>

python3 scripts/cli.py threads <owner/repo> <pr_number>

python3 scripts/cli.py findings <owner/repo> <pr_number> --input <path>|-

python3 scripts/cli.py adapter <owner/repo> <pr_number> <adapter_cmd...>

仅当高级入口不适用时，才使用内部低级调度。
仅处理未解决的GitHub线程和未关闭的本地结果。
对于GitHub评审线程，回复和解决操作都是必须的。
已过时/标记为
```
STALE
```
的GitHub线程在未明确处理前仍视为未解决。
对于本地结果，最终处理必须包含备注。
```
producer=code-review
```
必须在会话处理开始前输出结果JSON。
在
```
python3 scripts/cli.py final-gate
```
通过前，不得宣布完成。

Automatic Iteration

自动迭代

The default review entrypoint runs repeated intake, item selection, action execution, and gate evaluation internally until the PR session converges.

The internal fixer handoff path uses the current AI agent by default.
If a finding cannot be resolved automatically, the workflow records an internal fixer request artifact for the agent to handle.
Advanced external fixer commands remain available for integrations that need an explicit command boundary.
External fixer commands must read a JSON payload from stdin and return a JSON object containing:
- ```
resolution
```
  :
```
fix
```
  ,
```
clarify
```
  , or
```
defer
```
- ```
note
```
- for GitHub thread
```
fix
```
  :
```
fix_reply
```
  - ```
  commit_hash
```
- ```
files
```
  - optional
```
severity
```
    ,
```
why
```
    ,
```
test_command
```
    ,
```
test_result
```
  - ```
  validation_commands
```
  may be used as the default validation evidence when
```
  test_command
```
  /
```
  test_result
```
  are omitted
- for GitHub thread
```
clarify
```
  or
```
defer
```
  :
```
reply_markdown
```
- optional
```
validation_commands
```
```
code-review
```
and
```
json
```
producers are consumed once per review run.
```
adapter
```
producer is re-run on each iteration.
The workflow exits as:
- ```
PASSED
```
  when gate succeeds
- ```
NEEDS_HUMAN
```
  when retry thresholds are exceeded
- ```
BLOCKED
```
  when a non-recoverable orchestration step fails

默认的评审入口会在内部重复执行输入、项选择、操作执行和校验门评估，直到PR会话收敛。

内部修复交接路径默认使用当前AI Agent。
如果某个结果无法自动解决，工作流会记录一个内部修复请求工件供Agent处理。
对于需要显式命令边界的集成，仍可使用高级外部修复命令。
外部修复命令必须从stdin读取JSON payload，并返回包含以下内容的JSON对象：
- ```
resolution
```
  :
```
fix
```
  、
```
clarify
```
  或
```
defer
```
- ```
note
```
- 针对GitHub线程的
```
fix
```
  操作：
```
fix_reply
```
  - ```
  commit_hash
```
- ```
files
```
  - 可选的
```
severity
```
    、
```
why
```
    、
```
test_command
```
    、
```
test_result
```
  - 当省略
```
test_command
```
    /
```
test_result
```
    时，
```
validation_commands
```
    可作为默认的验证证据
- 针对GitHub线程的
```
clarify
```
  或
```
defer
```
  操作：
```
reply_markdown
```
- 可选的
```
validation_commands
```
```
code-review
```
和
```
json
```
生产者在每次评审运行中仅被读取一次。
```
adapter
```
生产者在每次迭代中都会重新运行。
工作流会以下列状态退出：
- ```
PASSED
```
  ：校验门成功
- ```
NEEDS_HUMAN
```
  ：超过重试阈值
- ```
BLOCKED
```
  ：不可恢复的编排步骤失败

Producer Contract

生产者约定

gh-address-cr

is the orchestrator. Producers are replaceable.

```
code-review
```
is a producer, not the session owner.
```
code-review
```
here means "review-style findings producer", not one mandatory skill name.
```
code-review
```
now uses the built-in
```
code-review-adapter
```
backend for structured intake.
If the upstream review output is fixed-format
```
finding
```
blocks, normalize it with
```
review-to-findings
```
before ingestion.
```
review-to-findings
```
does not accept arbitrary Markdown prose.
```
gh-address-cr
```
only assumes the normalized finding contract:
- ```
title
```
- ```
body
```
- ```
path
```
- ```
line
```
Accepted findings input shapes:
- JSON array of finding objects
- JSON object with
```
findings
```
  ,
```
issues
```
  , or
```
results
```
- NDJSON, one finding object per line

Accepted field aliases:

```
path
```
or
```
file
```
or
```
filename
```
```
line
```
or
```
start_line
```
or
```
position
```
```
title
```
or
```
rule
```
or
```
check
```
```
body
```
or
```
message
```
or
```
description
```

Input path rule:
- use
```
--input <path>
```
  only when a producer already emitted a real JSON file
- otherwise prefer
```
--input -
```
  and pipe findings through
```
stdin
```
- do not create ad-hoc temporary findings files in the project workspace just to drive the workflow
Refresh rule:
- use
```
--sync
```
  when re-ingesting the same source and you want missing local findings to auto-close
Supported dispatch paths live in:
- ```
references/mode-producer-matrix.md
```

gh-address-cr

是编排器，生产者可替换。

```
code-review
```
是生产者，而非会话所有者。
此处的
```
code-review
```
指"评审风格的结果生产者"，而非某个必须的skill名称。
```
code-review
```
目前使用内置的
```
code-review-adapter
```
后端进行结构化输入。
如果上游评审输出是固定格式的
```
finding
```
块，在导入前需使用
```
review-to-findings
```
进行标准化。
```
review-to-findings
```
不接受任意Markdown文本。
```
gh-address-cr
```
仅依赖标准化的结果约定：
- ```
title
```
- ```
body
```
- ```
path
```
- ```
line
```
接受的结果输入格式：
- 结果对象的JSON数组
- 包含
```
findings
```
  、
```
issues
```
  或
```
results
```
  的JSON对象
- NDJSON，每行一个结果对象

接受的字段别名：

```
path
```
或
```
file
```
或
```
filename
```
```
line
```
或
```
start_line
```
或
```
position
```
```
title
```
或
```
rule
```
或
```
check
```
```
body
```
或
```
message
```
或
```
description
```

输入路径规则：
- 仅当生产者已生成真实JSON文件时，使用
```
--input <path>
```
- 否则优先使用
```
--input -
```
  并通过stdin管道传输结果
- 不要为了驱动工作流而在项目工作区中创建临时结果文件
刷新规则：
- 当重新导入同一来源且希望自动关闭缺失的本地结果时，使用
```
--sync
```
支持的调度路径请参考：
- ```
references/mode-producer-matrix.md
```

Discovery Rules

适用场景

Use this skill when the task involves one or more of these needs:

handle GitHub PR review threads with explicit reply and resolve steps
ingest local review findings into a PR-scoped session
run a final gate before declaring review completion
keep remote threads and local findings under one auditable PR session

Do not use this skill as the review engine itself.

It manages intake, state, processing discipline, and gating.
It does not own the reasoning logic of external review producers.

当任务涉及以下一项或多项需求时，使用此skill：

处理GitHub PR评审线程，包含明确的回复和解决步骤
将本地评审结果导入PR范围的会话
在宣布评审完成前运行最终校验门
在一个可审计的PR会话中管理远程线程和本地结果

请勿将此skill用作评审引擎本身。

它负责输入、状态、处理规范和校验门管理。
它不拥有外部评审生产者的推理逻辑。

Decision Matrix

决策矩阵

Accept: real bug or low-cost valid improvement; fix and provide evidence.
Clarify: reviewer misunderstood the code; explain without changing code.
Defer: non-blocking or high-cost preference; explain the tradeoff.
Reject: suggestion is technically incorrect, conflicts with the current contract, or would break an intentional compatibility guarantee.

接受：真实bug或低成本的有效改进；修复并提供证据。
澄清：评审者误解了代码；无需修改代码，仅作解释。
推迟：非阻塞或高成本的偏好；解释权衡理由。
拒绝：建议在技术上不正确、与当前约定冲突，或会破坏有意的兼容性保证。

Fix Selection Rules

修复选择规则

Before changing code, classify each item in this order:

Validity
- ```
confirmed
```
  : reproducible in current HEAD or directly supported by code/tests
- ```
unclear
```
  : not yet verified; do not implement blindly
- ```
rejected
```
  : technically incorrect or based on missing context
Impact
- Does it affect correctness, session/gate consistency, runtime safety, compatibility, packaging, or CI?
Scope Fit
- Is the fix local to the current PR, or does it expand into a new design decision or larger refactor?
Decision
- ```
fix
```
  ,
```
clarify
```
  ,
```
defer
```
  , or
```
reject
```

Use these defaults:

Default to
```
fix
```
for correctness bugs, state mismatches, concurrency hazards, compatibility regressions, install/runtime breakage, and P1/P2 issues that can be verified.
Default to
```
clarify
```
when behavior is intentional and the reviewer lacks context.
Default to
```
defer
```
when the issue is real but out of scope for the current PR or would force broader redesign.
Default to
```
reject
```
when the suggestion is technically unsound or would violate an explicit workflow contract.

Do not change code until the item has been validated and classified.

在修改代码前，按以下顺序对每个项进行分类：

有效性
- ```
confirmed
```
  ：在当前HEAD中可复现，或直接由代码/测试支持
- ```
unclear
```
  ：尚未验证；不要盲目实现
- ```
rejected
```
  ：技术上不正确或基于缺失的上下文
影响
- 它是否影响正确性、会话/校验门一致性、运行时安全性、兼容性、打包或CI？
范围适配性
- 修复是否局限于当前PR，还是会扩展为新的设计决策或更大规模的重构？
决策
- ```
fix
```
  、
```
clarify
```
  、
```
defer
```
  或
```
reject
```

使用以下默认规则：

对于正确性bug、状态不匹配、并发风险、兼容性回归、安装/运行时故障以及可验证的P1/P2问题，默认选择
```
fix
```
。
当行为是有意设计且评审者缺乏上下文时，默认选择
```
clarify
```
。
当问题真实存在但超出当前PR范围，或会迫使进行更广泛的重新设计时，默认选择
```
defer
```
。
当建议在技术上不合理或违反明确的工作流约定时，默认选择
```
reject
```
。

在项经过验证和分类前，请勿修改代码。

Scope Guardrails

范围约束

Do not "fix" items just to make the thread disappear.

Do not expand the PR with unrelated refactors.
Do not change public behavior for style-only comments.
Do not weaken compatibility defaults unless the review identifies a real regression.
Do not let a reviewer preference override an existing, tested contract without explicit product intent.

If a review item is real but not appropriate for the current PR, reply with

defer

and a concrete rationale instead of stretching scope.

不要为了让线程消失而"修复"项。

不要在PR中添加无关的重构内容。
不要因仅涉及风格的评论而修改公共行为。
除非评审指出真实的回归问题，否则不要弱化兼容性默认设置。
在没有明确产品意图的情况下，不要让评审者的偏好覆盖已有的、经过测试的约定。

如果评审项真实存在但不适合当前PR，请回复

defer

并给出具体理由，而非扩大范围。

Needs-Human Escalation

需要人工介入的升级场景

Prefer

NEEDS_HUMAN

over speculative fixes when:

the claim cannot be verified from the codebase or tests
two valid concerns conflict and require a product decision
the fix would create a new interface or contract
the same item keeps reopening after multiple technically sound attempts
the suggestion conflicts with an intentional compatibility or workflow rule and the tradeoff is not obvious

gh-address-cr

should stop iteration and escalate rather than forcing an implementation under uncertainty.

在以下情况下，优先选择

NEEDS_HUMAN

而非推测性修复：

无法从代码库或测试中验证该主张
两个有效的关注点冲突，需要产品决策
修复会创建新的接口或约定
同一问题在多次技术上合理的尝试后仍反复出现
建议与有意的兼容性或工作流规则冲突，且权衡不明显

gh-address-cr

应停止迭代并升级，而非在不确定的情况下强制实现。

Agent Feedback

Agent反馈

When the skill itself blocks progress, file a feedback issue against the skill repository before giving up.
Use feedback issues for skill-level problems such as contradictory instructions, missing automation, documentation gaps, or repeatable tooling failures that are not caused by the repository under review.
Do not file feedback issues for normal PR findings, code bugs in the target repository, or expected wait states such as
```
WAITING_FOR_EXTERNAL_REVIEW
```
.
Do not include usernames, emails, tokens, machine names, or absolute local paths in feedback issues.
Prefer safe technical diagnostics such as failing command, exit code, status,
```
reason_code
```
,
```
waiting_on
```
,
```
run_id
```
, and skill version.
When
```
--using-repo
```
and
```
--using-pr
```
are present,
```
submit_feedback.py
```
auto-collects local PR-workspace evidence from
```
last-machine-summary.json
```
,
```
session.json
```
,
```
audit_summary.md
```
, and cached PR head SHA when those files exist.
Repeated feedback is deduplicated by fingerprint; if the same feedback issue is already open, or was closed recently inside the cooldown window, the helper returns the existing issue instead of creating a new one.

Use

python3 scripts/submit_feedback.py

with explicit fields so the body matches the repository issue format:

```
--category
```
```
--title
```
```
--summary
```
```
--expected
```
```
--actual
```

optional

--source-command

--failing-command

--exit-code

--status

--reason-code

--waiting-on

--run-id

--skill-version

--using-repo

--using-pr

--artifact

, and

--notes

Example:

python3 scripts/submit_feedback.py --category workflow-gap --title "blocked without a recovery step" --summary "review stopped in a blocked state without enough operator guidance." --expected "the skill should identify the next command or artifact to inspect." --actual "the workflow stopped and the next action was ambiguous." --source-command "python3 scripts/cli.py review owner/repo 123" --failing-command "python3 scripts/cli.py final-gate owner/repo 123" --exit-code 5 --status BLOCKED --reason-code WAITING_FOR_FIX --waiting-on human_fix --run-id cr-loop-20260417T120000Z --skill-version 1.2.0 --using-repo owner/repo --using-pr 123 --artifact /tmp/loop-request.json

python3 scripts/cli.py submit-feedback --category workflow-gap --title "blocked without a recovery step" --summary "review stopped in a blocked state without enough operator guidance." --expected "the skill should identify the next command or artifact to inspect." --actual "the workflow stopped and the next action was ambiguous."

当skill本身阻碍进展时，在放弃前请向skill仓库提交反馈issue。
反馈issue用于skill级别的问题，如矛盾的指令、缺失的自动化、文档缺口或可重复的工具故障，且这些问题并非由被评审的仓库导致。
请勿为正常的PR结果、目标仓库中的代码bug或
```
WAITING_FOR_EXTERNAL_REVIEW
```
等预期等待状态提交反馈issue。
请勿在反馈issue中包含用户名、邮箱、令牌、机器名称或绝对本地路径。
优先使用安全的技术诊断信息，如失败的命令、退出码、状态、
```
reason_code
```
、
```
waiting_on
```
、
```
run_id
```
和skill版本。
当
```
--using-repo
```
和
```
--using-pr
```
存在时，
```
submit_feedback.py
```
会自动从
```
last-machine-summary.json
```
、
```
session.json
```
、
```
audit_summary.md
```
和缓存的PR head SHA（如果这些文件存在）中收集本地PR工作区的证据。
重复的反馈会通过指纹去重；如果相同的反馈issue已存在，或在冷却窗口内最近被关闭，助手会返回已有的issue而非创建新的。

使用

python3 scripts/submit_feedback.py

并指定明确字段，使内容符合仓库issue格式：

```
--category
```
```
--title
```
```
--summary
```
```
--expected
```
```
--actual
```

可选的

--source-command

、

--failing-command

、

--exit-code

、

--status

、

--reason-code

、

--waiting-on

、

--run-id

、

--skill-version

、

--using-repo

、

--using-pr

、

--artifact

和

--notes

示例：

python3 scripts/submit_feedback.py --category workflow-gap --title "blocked without a recovery step" --summary "review stopped in a blocked state without enough operator guidance." --expected "the skill should identify the next command or artifact to inspect." --actual "the workflow stopped and the next action was ambiguous." --source-command "python3 scripts/cli.py review owner/repo 123" --failing-command "python3 scripts/cli.py final-gate owner/repo 123" --exit-code 5 --status BLOCKED --reason-code WAITING_FOR_FIX --waiting-on human_fix --run-id cr-loop-20260417T120000Z --skill-version 1.2.0 --using-repo owner/repo --using-pr 123 --artifact /tmp/loop-request.json

python3 scripts/cli.py submit-feedback --category workflow-gap --title "blocked without a recovery step" --summary "review stopped in a blocked state without enough operator guidance." --expected "the skill should identify the next command or artifact to inspect." --actual "the workflow stopped and the next action was ambiguous."

Required Evidence

必需证据

Accepted GitHub thread:
- commit
- touched files
- validation command and result
Clarified or deferred item:
- rationale
Local finding terminal state:
- note

已处理的GitHub线程：
- commit
- 修改的文件
- 验证命令及结果
已澄清或推迟的项：
- 理由
本地结果的最终状态：
- 备注

Completion Contract

完成约定

Final output must include:

```
final_gate
```
command used
```
Verified: 0 Unresolved Threads found
```
```
Verified: 0 Pending Reviews found
```
unresolved GitHub threads = 0
session blocking items = 0
audit summary path + sha256

For run-scoped diagnostics, use:

python3 scripts/audit_report.py --run-id <run_id> <owner/repo> <pr_number>

successful

python3 scripts/cli.py final-gate --auto-clean ...

runs archive the PR workspace before deletion under

archive/<owner>__<repo>/pr-<pr>/<run_id>/

最终输出必须包含：

使用的
```
final_gate
```
命令
```
Verified: 0 Unresolved Threads found
```
```
Verified: 0 Pending Reviews found
```
未解决的GitHub线程数 = 0
会话阻塞项数 = 0
审计摘要路径 + sha256

如需运行范围的诊断信息，使用：

python3 scripts/audit_report.py --run-id <run_id> <owner/repo> <pr_number>

成功运行的

python3 scripts/cli.py final-gate --auto-clean ...

会在删除前将PR工作区归档到

archive/<owner>__<repo>/pr-<pr>/<run_id>/

目录下

Must-Fix Rule

必须修复规则

Default must-fix: correctness bugs, data loss risks, platform/runtime breakage, packaging/install breakage, P1/P2 regressions.
Can defer with rationale: style-only, naming preference, non-blocking wording improvements.
For this repo, fix priority is:
- session / gate / iteration semantic mismatches
- GitHub reply / resolve / pending-review visibility issues
- CLI and shell-wrapper compatibility regressions
- workspace/cache side effects
- test and CI breakage caused by real implementation changes
- documentation/runtime mismatches that mislead actual usage

默认必须修复：正确性bug、数据丢失风险、平台/运行时故障、打包/安装故障、P1/P2回归问题。
可附带理由推迟：仅涉及风格、命名偏好、非阻塞的措辞改进。
对于本仓库，修复优先级为：
- 会话/校验门/迭代语义不匹配
- GitHub回复/解决/待评审可见性问题
- CLI和shell-wrapper兼容性回归
- 工作区/缓存副作用
- 由真实实现变更导致的测试和CI故障
- 误导实际使用的文档/运行时不匹配

Why CR Appears Later (Use This Exact Logic)

为何CR出现在后期（请严格遵循此逻辑）

GitHub review bots run asynchronously.
New commits trigger re-analysis and can generate new comments.
Old threads can become outdated; new ones may appear on different lines.

GitHub评审机器人异步运行。
新提交会触发重新分析，并可能生成新的评论。
旧线程可能过时；新线程可能出现在不同行。

References

参考

dispatch matrix:
```
references/mode-producer-matrix.md
```
checklist:
```
references/cr-triage-checklist.md
```
stable operator surface:
```
python3 scripts/cli.py
```
preferred automation surface:
```
python3 scripts/cli.py ...
```
AI agent feedback helper:
```
python3 scripts/submit_feedback.py
```

code-review bridge prompt:

python3 scripts/cli.py prepare-code-review <local|mixed> <owner/repo> <pr_number>

Markdown-to-findings converter:

python3 scripts/cli.py review-to-findings <owner/repo> <pr_number> --input -

code-review adapter backend:

python3 scripts/cli.py code-review-adapter --input -

调度矩阵：
```
references/mode-producer-matrix.md
```
检查清单：
```
references/cr-triage-checklist.md
```
稳定的操作员接口：
```
python3 scripts/cli.py
```
首选自动化接口：
```
python3 scripts/cli.py ...
```
AI Agent反馈助手：
```
python3 scripts/submit_feedback.py
```

代码评审桥接提示：

python3 scripts/cli.py prepare-code-review <local|mixed> <owner/repo> <pr_number>

Markdown转结果转换器：

python3 scripts/cli.py review-to-findings <owner/repo> <pr_number> --input -

代码评审适配器后端：

python3 scripts/cli.py code-review-adapter --input -