pre-pr-greptile

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pre-PR Greptile Review

PR创建前的Greptile审查

A pre-PR review gate. Greptile reviews the committed branch's diff on its own cloud (≈$0 Claude tokens, ~$1/review after the monthly free tier), and this skill triages the result and drives the PR. It is a GATE, not blind automation: the review output is verified and risky findings are proposed, not auto-applied.

Mirrors Greptile's own official

cli-review

skill (whoami →

--json

primary,

--agent

fallback, findings ranked by severity) and adapts its

greploop

iterate-until-clean idea to the LOCAL CLI (greploop itself drives the PR bot via

gh

, not the local review).

这是一个PR创建前的审查关卡。Greptile会在其云端对已提交分支的代码差异进行审查（每月免费额度之外，每次审查约1美元，Claude令牌成本约为0），本Skill会对审查结果进行分类处理并推进PR创建流程。这是一个关卡机制，而非盲目自动化：审查输出会被验证，高风险的发现仅会提出建议，不会自动应用。

本Skill镜像了Greptile官方的

cli-review

Skill（通过

greptile whoami --json

作为主要方式，

--agent

作为 fallback，发现的问题按严重程度排序），并将其

greploop

的“迭代直至无问题”理念适配到本地CLI（greploop本身通过

gh

驱动PR机器人，而非本地审查）。

Prerequisites

前提条件

Preflight (mirrors greptile's official
cli-review
):
```
git rev-parse --show-toplevel
```
(confirm you're in a repo) →
```
command -v greptile
```
(CLI present) →
```
greptile whoami
```
(auth). Greptile has NO
```
--fix
```
/apply command — it only PRODUCES findings; the agent applies the fixes (exactly like the official
```
greploop
```
skill, which edits files itself).
Auth (do NOT
greptile login
from an agent/wrapped shell). Check with a non-interactive
```
greptile whoami
```
. If unauthenticated, STOP and tell the user to run
```
greptile login
```
in a native terminal (the browser-OAuth callback is unreliable in wrapped/non-interactive shells — it fails with a malformed
```
redirect_uri
```
). Headless fallback:
```
export GREPTILE_API_KEY=…
```
or
```
echo "$GREPTILE_API_KEY" | greptile login --api-key
```
(never pass the key as a CLI arg — shell history/process list).
greptile installed (
```
command -v greptile
```
). If absent/down/rate-limited → STOP and surface to the user; never hang and never silently open the PR (see Fail-open).

预检查（与Greptile官方
cli-review
一致）：执行
```
git rev-parse --show-toplevel
```
（确认当前处于仓库目录）→
```
command -v greptile
```
（检查CLI是否存在）→
```
greptile whoami
```
（验证身份）。Greptile没有
```
--fix
```
/应用命令——它仅生成问题发现结果；由Agent来应用修复（与官方
```
greploop
```
Skill完全相同，后者会自行编辑文件）。
身份验证（请勿从Agent/封装Shell中执行
greptile login
）。通过非交互式的
```
greptile whoami
```
检查。如果未通过验证，请停止操作并告知用户在原生终端中执行
```
greptile login
```
（在封装/非交互式Shell中，浏览器OAuth回调不可靠——会因
```
redirect_uri
```
格式错误而失败）。无界面环境的 fallback 方案：
```
export GREPTILE_API_KEY=…
```
或
```
echo "$GREPTILE_API_KEY" | greptile login --api-key
```
（切勿将密钥作为CLI参数传递——会被记录到Shell历史/进程列表中）。
已安装Greptile（通过
```
command -v greptile
```
检查）。如果未安装/服务不可用/触发速率限制→停止操作并告知用户；切勿挂起或静默创建PR（参见故障开放机制）。

The flow

流程步骤

Be on a feature branch with the work committed. If on a trunk/base branch (
```
testing
```
,
```
main
```
,
```
develop
```
) create
```
feature|bugfix|hotfix/<ticket>-slug
```
first. Greptile reviews the branch diff vs its base, so the work must be committed. Keep every commit SSH-signed (never
```
--no-gpg-sign
```
, never
```
--no-verify
```
).
Resolve the base branch explicitly — never assume
main
. In this org PRs target
```
testing
```
(the trunk); confirm per repo.
```
greptile review
```
defaults to the repo's default branch, which may be wrong — pass
```
-b <base>
```
to match the intended PR base.
Run the review:
```
greptile review -b <base> --json
```
(primary; introspect the shape with
```
jq 'keys'
```
— the JSON schema is undocumented, do not hard-code field names). Fall back to
```
greptile review -b <base> --agent
```
(plain text) if JSON fails.
VERIFY the review matches THIS branch before trusting ANY finding. Compare the review's referenced files against
```
git diff <base>...HEAD --name-only
```
(three-dot = merge-base, the PR diff). The review's files must be a subset of the branch diff. If they don't overlap, or the review returns in under ~10s (a cache hit), it is a STALE / different-repo review — discard it, run ONCE more fresh, and if it still mismatches, STOP and surface. NEVER apply fixes from an unverified review. (This guard exists because a first-call greptile review was observed returning a cached review of a completely different repository.)
Triage findings (verified review only): rank by severity. Tier each finding:
- Mechanical / low-risk (unused import, typo, missing null-guard, docs/test gap): safe to fix directly.
- Risky (auth, crypto, injection, data-loss, concurrency, or ANY logic/behavior change): do NOT auto-apply — propose the diff and get explicit user approval first.
- False positive / intent-conflicting: do not apply; record the rationale (for the PR body / a later thread reply). Never weaken correctness or security to silence a nit.
Apply fixes, mind the SDD gate. Editing production source (
```
.py/.ts/.vue/…
```
) fires the global
```
sdd_gate
```
PreToolUse hook, which BLOCKS when the repo is an OpenSpec project with no active change — which is the normal state at PR time (all tasks
```
- [x]
```
). If a production-source fix is blocked: surface it and let the user decide (keep a task open, reopen a change, or apply manually). Do not auto-set
```
SDD_HOOKS_DISABLED=1
```
— that defeats the user's spec-first discipline. Fixes under
```
docs/
```
, tests,
```
.claude/
```
, and
```
openspec/
```
are exempt and apply freely.
Re-commit the fixes (signed; prefer
```
--fixup
```
+ autosquash or a small focused commit so the PR history stays clean), then re-run a FRESH
greptile review
and re-do step 4's diff-match.
```
--resume
```
is ONLY for continuing a crashed/interrupted review — it does NOT re-review a new commit, so never use it after applying fixes.
Loop to convergence, cap at 3 reviews. Stop early when only nits/false-positives remain or a finding recurs (the fix didn't satisfy it → human call). Count BILLABLE reviews (initial + every re-run + any stale re-run) — each is ~$1 after the free tier, so don't re-run gratuitously. If not clean after 3, STOP, do NOT create the PR, and surface the remaining findings.
Ensure the correct gh account, push, then open the PR.
```
gh auth status
```
; if it drifted,
```
gh auth switch --user <correct-account>
```
(a wrong account → push/
```
gh pr create
```
404 "Repository not found").
```
git push
```
(signed) the branch, then
```
gh pr create --base <base>
```
— no Claude/Anthropic co-author trailer, no "Generated with Claude Code" footer, never
```
--no-verify
```
. Never merge the base into the feature branch.

切换到已完成工作提交的功能分支。如果当前处于主干/基础分支（如
```
testing
```
、
```
main
```
、
```
develop
```
），请先创建
```
feature|bugfix|hotfix/<ticket>-slug
```
格式的分支。Greptile会审查该分支与基础分支的差异，因此工作内容必须已提交。确保每个提交都通过SSH签名（切勿使用
```
--no-gpg-sign
```
或
```
--no-verify
```
）。
明确指定基础分支——切勿默认假设为
main
。在本组织中，PR目标分支为
```
testing
```
（主干）；请根据仓库确认。
```
greptile review
```
默认使用仓库的默认分支，这可能不符合需求——需传递
```
-b <base>
```
参数以匹配预期的PR基础分支。
执行审查：
```
greptile review -b <base> --json
```
（主要方式；可通过
```
jq 'keys'
```
查看JSON结构——该JSON schema未公开，请勿硬编码字段名）。如果JSON方式失败， fallback 到
```
greptile review -b <base> --agent
```
（纯文本格式，供Agent使用）。
在信任任何发现结果之前，验证审查是否匹配当前分支。将审查中提及的文件与
```
git diff <base>...HEAD --name-only
```
（三点表示合并基准，即PR的代码差异）的结果进行对比。审查中的文件必须是分支差异文件的子集。如果两者不重叠，或者审查在约10秒内返回（缓存命中），则说明这是过期/来自其他仓库的审查结果——请丢弃该结果，重新执行一次全新的审查；如果仍然不匹配，请停止操作并告知用户。切勿应用未经验证的审查结果中的修复方案。（设置此防护是因为曾观察到首次调用Greptile审查时，返回的是完全不同仓库的缓存审查结果。）
分类处理发现的问题（仅针对已验证的审查结果）：按严重程度排序。将每个发现分为以下层级：
- 机械性/低风险问题（未使用的导入、拼写错误、缺失空值校验、文档/测试缺口）：可直接安全修复。
- 高风险问题（认证、加密、注入、数据丢失、并发问题，或任何逻辑/行为变更）：请勿自动应用修复——先提出差异方案并获得用户明确批准。
- 误报/与意图冲突的问题：请勿应用；记录理由（用于PR正文或后续线程回复）。切勿为了消除无关建议而削弱正确性或安全性。
应用修复方案，注意SDD关卡。编辑生产源代码（
```
.py/.ts/.vue/…
```
）会触发全局
```
sdd_gate
```
PreToolUse钩子，当仓库是OpenSpec项目且没有活跃变更时（这是PR阶段的正常状态，所有任务均已标记
```
- [x]
```
），该钩子会阻止操作。如果生产源代码修复被阻止：告知用户并让其决定（保留一个未完成任务、重新开启变更或手动应用修复）。请勿自动设置
SDD_HOOKS_DISABLED=1
——这会违背用户的“先规范后代码”原则。
```
docs/
```
、测试文件、
```
.claude/
```
和
```
openspec/
```
下的修复不受限制，可自由应用。
重新提交修复内容（需签名；优先使用
```
--fixup
```
+自动压缩或小型聚焦提交，以保持PR历史整洁），然后**重新执行一次全新的
```
greptile review
```
**并重复步骤4的差异匹配检查。
```
--resume
```
仅用于恢复崩溃/中断的审查——它不会重新审查新的提交，因此在应用修复后切勿使用。
循环直至收敛，最多执行3次审查。当仅剩下无关建议/误报，或者某个问题反复出现（修复方案未满足要求→需人工决策）时，提前停止。统计计费审查次数（初始审查+每次重新审查+任何针对过期结果的重新审查）——免费额度之外每次约1美元，因此请勿 gratuitously 重复执行。如果3次审查后仍未达到“无问题”状态，请停止操作，不要创建PR，并告知用户剩余的问题。
确保使用正确的gh账户，推送分支后创建PR。执行
```
gh auth status
```
；如果账户漂移，执行
```
gh auth switch --user <correct-account>
```
（错误账户会导致推送/
```
gh pr create
```
时出现404“仓库未找到”错误）。推送（已签名）分支，然后执行
```
gh pr create --base <base>
```
——不要添加Claude/Anthropic联合作者信息，不要添加“Generated with Claude Code”页脚，切勿使用
```
--no-verify
```
。切勿将基础分支合并到功能分支中。

Definition of "clean"

“无问题”的定义

Zero unresolved findings you agreed with. Nits, suggestions, and documented false positives do NOT block. Persist skipped-finding rationale so the loop stops re-fighting the same false positive and the gate can pass with recorded waivers.

零未解决且你认可的问题。无关建议、改进建议和已记录的误报不会阻碍流程。保留跳过问题的理由，以便循环停止重复处理同一误报，且关卡可在记录豁免的情况下通过。

Fail-open / fail-safe

故障开放/故障安全机制

A gate must neither deadlock nor silently bypass. If greptile is missing, unauthenticated (in this shell), erroring, or rate-limited: STOP and hand the decision to the user — never hang, never open the PR silently. If the user explicitly says to skip the review, honor it and note in the PR body that the greptile pre-flight was skipped.

关卡既不能死锁也不能静默绕过。如果Greptile缺失、未通过身份验证（在当前Shell中）、报错或触发速率限制：停止操作并将决策权交给用户——切勿挂起或静默创建PR。如果用户明确要求跳过审查，请遵从并在PR正文中注明已跳过Greptile预检查。

Guardrails

防护规则

Never act on a review that fails the diff-match check (step 4). Sub-10s return = suspect.
Never auto-apply security/behavior-changing findings — propose for approval.
Never bypass the SDD gate or commit signing to make the loop proceed.
Keep fixes minimal and on-topic; don't scope-creep the branch to satisfy unrelated nits.
The optional post-PR summary comment must not publicly expose reasoning about security issues you chose not to fix — keep it to resolved items or scrub sensitive detail.
Each auto-fix edit also triggers whatever PostToolUse hooks and the
```
Stop
```
```
test_gate
```
are configured in this environment — budget for that latency and let those tests be part of "clean".

切勿对未通过差异匹配检查（步骤4）的审查结果采取行动。10秒内返回的结果应视为可疑。
切勿自动应用涉及安全/行为变更的修复方案——仅提出建议等待批准。
切勿绕过SDD关卡或提交签名要求以推进循环。
修复方案应尽可能精简且紧扣主题；不要为了满足无关建议而扩大分支范围。
可选的PR后总结评论不得公开暴露关于你选择不修复的安全问题的推理过程——仅提及已解决的问题或删除敏感细节。
每次自动修复编辑还会触发当前环境中配置的所有PostToolUse钩子和
```
Stop
```
```
test_gate
```
——请考虑延迟问题，并将这些测试视为“无问题”状态的一部分。

Commands

命令

bash

greptile whoami                      # auth check (never `greptile login` from a wrapped shell)
greptile review -b testing --json    # primary: machine-readable, explicit base
greptile review -b testing --agent   # fallback: plain text for agents
git diff testing...HEAD --name-only  # the diff the review MUST match (step 4)
greptile review show <id>            # reopen a past review
gh auth switch --user <account>      # fix account drift before push / gh pr create

bash

greptile whoami                      # 身份验证检查（切勿从封装Shell中执行`greptile login`）
greptile review -b testing --json    # 主要方式：机器可读格式，明确指定基础分支
greptile review -b testing --agent   # fallback：供Agent使用的纯文本格式
git diff testing...HEAD --name-only  # 审查结果必须匹配的代码差异（步骤4）
greptile review show <id>            # 重新查看过往审查结果
gh auth switch --user <account>      # 在推送/执行gh pr create前修复账户漂移问题