address-findings

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Address Findings

处理审查发现

Fix and resolve the open review findings on an Entire trail. A finding is a review comment posted to a trail on entire.io: it has a file/line location, a body, a severity, and sometimes a suggested unified-diff patch. This skill fetches the open findings, applies or hand-fixes each one in the current worktree, and marks it resolved on the trail.

修复并解决Entire trail上的未解决审查发现。发现是发布在entire.io平台trail上的审查评论：它包含文件/行位置、正文、严重程度，有时还附带建议的unified-diff补丁。本技能会获取未解决的发现，在当前工作树中应用或手动修复每个问题，并在trail上标记其已解决。

When to use / not use

使用场景与禁用场景

Use when the user points at a trail — a URL like

https://<host>/<forge>/<owner>/<repo>/trails/<number>/<slug>

, or a bare trail number or branch — and asks to address / fix / resolve its findings or review comments.

Do not use this skill for:

A code review of the current diff — that is the
```
review
```
skill (read-only).
Creating new findings — use
```
entire trail finding add
```
.

当用户指向某个trail（例如

https://<host>/<forge>/<owner>/<repo>/trails/<number>/<slug>

这样的URL，或者单纯的trail编号、分支名称），并要求处理/修复/解决其发现或审查评论时，使用本技能。

请勿将本技能用于：

当前差异的代码审查——这是
```
review
```
技能的用途（只读）。
创建新的发现——使用
```
entire trail finding add
```
命令。

Response Format

响应格式

Begin the first response to this skill invocation with the line:

Entire Address Findings:

followed by a blank line, then the content. Apply the header to the first response only. Omit it on error / early-exit responses (CLI missing, not authenticated, trail not found, branch mismatch, no open findings).

首次响应该技能调用时，需以以下行开头：

Entire Address Findings:

随后空一行，再添加内容。仅在首次响应中使用该标题。错误/提前退出响应（如CLI缺失、未认证、未找到trail、分支不匹配、无未解决发现）中无需添加。

Rules

规则

Make the smallest correct change that addresses each finding. Do not expand scope.
Only mark a finding resolved when you actually addressed it. If a finding is ambiguous or needs a human decision, leave it open and report it.
Do not commit or push. Leave changes in the working tree for the user to review.
Never weaken a test or assertion just to clear a finding.

做出能解决每个发现的最小正确修改，不要扩大范围。
仅在实际解决问题后才标记发现为已解决。如果发现模糊不清或需要人工决策，保持其为未解决状态并进行报告。
不要提交或推送修改。将更改留在工作树中供用户审查。
切勿为了清除发现而弱化测试或断言。

Process

流程

1. Verify the CLI

1. 验证CLI

Run

entire version

. If the command is not found, stop and tell the user: "The Entire CLI is required but not installed. Install it from https://entire.io/docs/cli and try again."

运行

entire version

命令。如果未找到该命令，停止操作并告知用户： "需要Entire CLI但未安装。请从https://entire.io/docs/cli安装后重试。"

2. Resolve the trail selector

2. 解析trail选择器

If the argument is a trail URL, take the number from the
```
/trails/<number>/
```
path segment and use that number.
If it is a bare trail number, id, or branch name, use it as-is.
If you cannot determine a trail, stop and ask the user for the trail URL or number.

Use this value as the

<trail>

selector for every command below.

entire trail

accepts a trail number, id, or branch name interchangeably, so no number lookup is needed — a branch name works directly.

如果参数是trail URL，从
```
/trails/<number>/
```
路径段中提取编号并使用该编号。
如果是单纯的trail编号、ID或分支名称，直接使用该值。
如果无法确定trail，停止操作并询问用户提供trail的URL或编号。

将此值作为后续所有命令的

<trail>

选择器。

entire trail

命令可互换接受trail编号、ID或分支名称，因此无需查找编号——分支名称可直接使用。

3. Fetch open findings

3. 获取未解决的发现

bash

entire trail finding list <trail> --json --status open

If the output reports that authentication is required, stop and tell the user: "
```
entire trail finding list
```
requires authentication. Run
```
entire login
```
and try again."
If the
```
trail finding
```
subcommand is unavailable, or the API reports the feature is not enabled, stop and tell the user that trail findings may not be enabled for this account or repository. Do not invent findings.
Parse the JSON. Each finding has an id, a severity, a status, a body, a location (file path + line range), and may include a suggested change (a unified diff).
If there are no open findings, report "No open findings on this trail." and stop.

bash

entire trail finding list <trail> --json --status open

如果输出显示需要认证，停止操作并告知用户： "
```
entire trail finding list
```
需要认证。请运行
```
entire login
```
后重试。"
如果
```
trail finding
```
子命令不可用，或API报告该功能未启用，停止操作并告知用户该账户或仓库可能未启用trail发现功能。请勿虚构发现。
解析JSON输出。每个发现包含ID、严重程度、状态、正文、位置（文件路径+行范围），可能还包含建议的修改（unified diff）。
如果没有未解决的发现，报告"此trail上无未解决发现。"并停止操作。

4. Branch guard (you must be on the trail's branch)

4. 分支校验（必须处于trail对应的分支）

entire trail finding apply

edits the local worktree, so you must be on the trail's branch before changing files.

bash

git rev-parse --abbrev-ref HEAD                # current branch
entire trail list --json --status any -n 200   # locate the trail's branch

Find the trail whose

number

branch

matches your selector and read its

branch

If the trail's branch differs from the current branch, stop and tell the user: "Trail
```
<trail>
```
targets branch
```
<trail-branch>
```
, but you are on
```
<current-branch>
```
. Check it out first (
```
entire trail checkout <trail>
```
) and re-run." Do not edit files.
If you cannot find the trail in the list (e.g. pagination), do not hard-fail: warn that you could not verify the branch, and ask the user to confirm they are on the trail's branch before you continue.

entire trail finding apply

会编辑本地工作树，因此在修改文件前必须处于trail对应的分支。

bash

git rev-parse --abbrev-ref HEAD                # 当前分支
entire trail list --json --status any -n 200   # 查找trail对应的分支

找到

number

或

branch

与选择器匹配的trail，并读取其

branch

值。

如果trail对应的分支与当前分支不同，停止操作并告知用户： "Trail
```
<trail>
```
目标分支为
```
<trail-branch>
```
，但当前处于
```
<current-branch>
```
分支。请先切换到该分支（运行
```
entire trail checkout <trail>
```
）后重新执行。" 请勿编辑文件。
如果在列表中未找到该trail（例如分页问题），不要直接失败：警告用户无法验证分支，并请求用户确认已处于trail对应的分支后再继续。

5. Address each finding

5. 处理每个发现

Process findings highest severity first (high → medium → low). For each:

If it has a suggested unified-diff change, dry-run it first:
bash
```
entire trail finding apply <trail> <finding-id> --check
```
If it applies cleanly, apply and resolve in one step:
bash
```
entire trail finding apply <trail> <finding-id> --resolve
```
Otherwise (no patch, the patch conflicts, or the fix needs reasoning): read the finding body, open the file at its location, and make the smallest correct edit that addresses it. If a fast, relevant local check exists for the touched code (a build or a focused test), run it. Then resolve:
bash
```
entire trail finding resolve <trail> <finding-id> -m "<one line: what you changed>"
```
If you cannot confidently address it (ambiguous, needs a product/design decision, or out of scope): leave it open, do not resolve it, and record it for the report.

按严重程度从高到低处理发现（高→中→低）。对于每个发现：

如果附带建议的unified-diff修改，先进行试运行：
bash
```
entire trail finding apply <trail> <finding-id> --check
```
如果能干净地应用，一步完成应用和标记已解决：
bash
```
entire trail finding apply <trail> <finding-id> --resolve
```
否则（无补丁、补丁冲突或修复需要逻辑判断）：阅读发现正文，打开对应位置的文件，做出能解决问题的最小正确修改。如果对修改后的代码有快速相关的本地检查（构建或聚焦测试），运行该检查。然后标记已解决：
bash
```
entire trail finding resolve <trail> <finding-id> -m "<一行描述：你做了什么修改>"
```
如果无法自信地解决问题（模糊不清、需要产品/设计决策或超出范围）：保持其为未解决状态，不要标记已解决，并在报告中记录该情况。

6. Report

6. 报告

Summarize:

Resolved via suggested patch — list finding ids and files.
Resolved via manual edit — list finding ids, files, and a one-line of what changed.
Left open for your decision — list finding ids and why.
Any errors encountered.

Remind the user the changes are uncommitted and ready for review.

总结内容：

通过建议补丁解决的问题——列出发现ID和文件。
通过手动编辑解决的问题——列出发现ID、文件以及一行修改描述。
留待你决策的未解决问题——列出发现ID及原因。
遇到的任何错误。

提醒用户修改尚未提交，已准备好供审查。

Failure modes

失败场景

CLI not installed → install message (step 1).
Not authenticated → "
```
entire trail finding list
```
requires authentication. Run
```
entire login
```
and try again."
Trail findings not enabled / API error → tell the user the feature may be unavailable; do not fabricate findings.
Trail not found → tell the user to check the URL or number; suggest
```
entire trail list --status any
```
.
Wrong branch → stop with the checkout instruction (step 4).
Patch does not apply → fall back to a manual edit; if you cannot fix it confidently, leave the finding open and report it.
Not a git repository → stop and tell the user to run from inside the trail's repo.

CLI未安装 → 显示安装提示（步骤1）。
未认证 → 提示"
```
entire trail finding list
```
需要认证。请运行
```
entire login
```
后重试。"
Trail发现功能未启用/API错误 → 告知用户该功能可能不可用；请勿虚构发现。
未找到trail → 告知用户检查URL或编号；建议运行
```
entire trail list --status any
```
。
分支错误 → 停止操作并给出切换分支的说明（步骤4）。
补丁无法应用 → 转为手动编辑；如果无法自信修复，保持发现为未解决状态并报告。
非git仓库 → 停止操作并告知用户请在trail对应的仓库内运行。