sol-loop

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

sol-loop

sol-loop

This is a workflow for making your code changes more correct before (or sometimes after) filing a pull request. tl;dr - use OpenAI's GPT Sol to review your code in a loop.
Make the most minimal possible changes to appease the Sol reviewers. Be careful of scope creep and don't be scared to push back.
这是一个用于在发起 pull request 之前(有时是在之后)提高代码变更正确性的工作流。tl;dr - 使用 OpenAI 的 GPT Sol 循环审查你的代码。
作出尽可能小的改动,以满足 Sol 审查意见。注意避免 scope creep,也不要害怕对审查意见提出异议。

Budget

Budget

  • Default: 3 rounds total. Round 1 is full. Later rounds check only changed code and open findings.
  • Extend to 5 only for security, permissions, auth, data loss, or state/concurrency, while a blocker or should stays open with evidence. Or when the user asks.
  • Stop early if a round returns only nits. Declined nits and comment, doc, or format-only fixes need no new round.
  • One reviewer only. Sol must not start subagents or reviewers.
  • Keep a ledger: id, severity, outcome, usage if returned. Never guess it.
  • 默认总共进行 3 轮。第 1 轮进行全面审查。后续轮次只检查变更代码和尚未解决的 findings。
  • 仅当涉及 security、permissions、auth、data loss 或 state/concurrency,且有 blocker 或 should 在有证据支持下仍未解决时,才将轮次延长至 5 轮。用户提出要求时也可延长。
  • 如果某轮只返回 nit,则提前结束。已拒绝的 nit,以及仅涉及 comment、doc 或 format 的修复不需要新一轮。
  • 仅限一名 reviewer。Sol 不得启动 subagents 或其他 reviewers。
  • 维护一个 ledger:id、severity、outcome,以及在返回时记录 usage。绝不猜测这些信息。

1. Scope

1. Scope

Run
git status --short
. Do not stash, discard, or include unrelated changes. Limit review to the change paths if they separate cleanly. Otherwise stop and ask.
Find the base after
git fetch origin
:
  • PR:
    gh pr view <n> --json baseRefName,headRefOid
    . Check out the branch only if clean. Confirm
    HEAD
    is the PR head, or ahead only by this change. Base:
    git merge-base HEAD origin/<baseRefName>
    .
  • Local:
    git merge-base HEAD origin/<default-branch>
    . No remote: a base the user names, or
    HEAD
    for uncommitted changes only.
The change is base to working tree in those paths, with untracked files. Use one diff command all rounds. State intent and out-of-scope in 1-2 sentences. Run covering checks. Do not send code this change breaks. Note missing or pre-failing checks in the brief.
运行
git status --short
。不要 stash、discard 或包含无关变更。如果变更路径能够干净地分离,则将审查限制在这些路径内。否则停止并询问用户。
在
git fetch origin
后找到 base:
  • PR:
    gh pr view <n> --json baseRefName,headRefOid
    。仅在状态 clean 时 checkout 该分支。确认
    HEAD
    是 PR head,或者仅比 base 多出本次变更。Base:
    git merge-base HEAD origin/<baseRefName>
    。
  • Local:
    git merge-base HEAD origin/<default-branch>
    。没有 remote 时,使用用户指定的 base;若仅有未提交变更,则使用
    HEAD
    。
本次变更即从 base 到这些路径下 working tree 的差异,并包含 untracked files。所有轮次都使用同一条 diff 命令。用 1~2 句话说明意图和 out-of-scope。运行覆盖此次变更的 checks。不要发送会被此变更破坏的代码。在 brief 中注明缺失的检查或审查前就已失败的检查。

2. Start Sol

2. Start Sol

In T3, call
orchestrator_capabilities
. Pick the latest Sol unless the user named a version. Do not hardcode an ID. Record provider, model, and effort only if exposed. Use
delegate_task
every round (
role: "review"
,
mode: "async"
). Save
taskId
. New
clientRequestId
per round.
childThreadId
is storage, not the next target. Do not use
t3_thread_send
,
create_threads
, or
t3_thread_launch
for review.
If T3 tools are not listed, try one direct capability call. Outside T3, use a native Sol subagent and keep its ID. In Claude Code, use a custom subagent only if it is set up to run Sol. If no route runs Sol, report the blocker. Do not substitute a model.
Do not edit scoped files while review runs. Wait for the notice. Do not poll or start a second reviewer. Timeout, error, or no reply is not approval. On failure, cancel, verify stop, restart with the ledger.
Round 1 brief (T3 children get no history):
Review only. Do not edit, commit, push, comment on PRs, or start subagents.
Repo: <abs path> Base: <sha> Intent: <intent> Out of scope: <scope> Checks: <results>
See: git diff <base> [-- <paths>]; git status --short (read untracked).
Read surrounding code. Find bugs, broken callers, mismatch with intent.
Skip style unless it hides a bug. Hold to the smallest change. Flag code,
tests, or guards the intent does not need. Other paths, rare cases, small
perf, extra compat: nits.
blocker = intended case wrong. should = real bug callers will hit, in intent. nit = rest.
Reply:
VERDICT: APPROVE or CHANGES
S1 [blocker|should|nit] <file>:<line> <claim>. Fix: <suggestion> (stable ids)
在 T3 中,调用
orchestrator_capabilities
。除非用户指定了版本,否则选择最新的 Sol。不要硬编码 ID。仅在接口提供这些信息时记录 provider、model 和 effort。每轮都使用
delegate_task
(
role: "review"
,
mode: "async"
)。保存
taskId
。每轮使用新的
clientRequestId
。
childThreadId
仅用于存储,不是下一轮的目标。审查时不要使用
t3_thread_send
、
create_threads
或
t3_thread_launch
。
如果未列出 T3 tools,尝试一次直接 capability call。在 T3 之外,使用原生 Sol subagent 并保留其 ID。在 Claude Code 中,仅当 custom subagent 已配置为运行 Sol 时才使用它。如果没有任何调用路径能运行 Sol,报告 blocker。不要用其他模型替代。
审查运行期间不要编辑 scoped files。等待通知。不要轮询或启动第二名 reviewer。超时、错误或无回复均不代表批准。失败时,取消任务、确认其已停止,然后根据 ledger 重新启动。
第 1 轮 brief(T3 children 不会获得历史记录):
Review only. Do not edit, commit, push, comment on PRs, or start subagents.
Repo: <abs path> Base: <sha> Intent: <intent> Out of scope: <scope> Checks: <results>
See: git diff <base> [-- <paths>]; git status --short (read untracked).
Read surrounding code. Find bugs, broken callers, mismatch with intent.
Skip style unless it hides a bug. Hold to the smallest change. Flag code,
tests, or guards the intent does not need. Other paths, rare cases, small
perf, extra compat: nits.
blocker = intended case wrong. should = real bug callers will hit, in intent. nit = rest.
Reply:
VERDICT: APPROVE or CHANGES
S1 [blocker|should|nit] <file>:<line> <claim>. Fix: <suggestion> (stable ids)

3. Answer findings

3. Answer findings

Check each finding and severity yourself. Another path, rare case, or small cost is a nit, whatever label it came with.
  • Agree: smallest fix. Prefer delete or narrow over new lock, cache, helper, or option. Fix the case that happened. Add one focused test that fails without the fix, if intent needs it.
  • Disagree: say why, with evidence (file:line, test, output).
  • Out of scope or nit: decline in one line. List as follow-up.
Update the ledger. Re-run checks and
git diff --shortstat <base>
. If review grew the diff, cut first. Do not agree just to end the loop.
亲自核查每个 finding 及其 severity。只要属于另一条路径、罕见情况或成本很小,无论最初标签是什么,都应视为 nit。
  • 同意:采用最小修复。相较于新增 lock、cache、helper 或 option,优先删除现有实现或缩小其范围。修复实际发生的情况。如果意图需要,添加一个在没有该修复时就会失败的聚焦测试。
  • 不同意:说明理由并提供证据(file:line、test、output)。
  • 范围外或 nit:用一行拒绝。列为 follow-up。
更新 ledger。重新运行 checks 和
git diff --shortstat <base>
。如果审查使 diff 增大,先缩小改动。不要为了结束循环而违心同意。

4. Next round

4. Next round

Start one only if budget remains and a blocker or should is open, behavior code changed, or approval does not cover the current behavior diff. Use a fresh
delegate_task
in T3, or follow up the saved native ID. Send the round 1 brief, the ledger (
fixed:
/
disagree:
/
declined:
+ evidence), the same base diff, and the change since last round. Tell Sol: open ids and changed code only. Mark each old id
resolved
or
still open: <reason>
.
仅当预算尚有剩余,并且存在以下任一情况时,才启动下一轮:有尚未解决的 blocker 或 should、行为相关代码发生变化,或批准未覆盖当前 behavior diff。在 T3 中使用新的
delegate_task
,或跟进已保存的原生 ID。将第 1 轮 brief、ledger(
fixed:
/
disagree:
/
declined:
+ 证据)、相同的 base diff,以及上一轮之后的变更发送给 Sol。告知 Sol:只关注未解决的 id 和变更代码。将每个旧 id 标记为
resolved
或
still open: <reason>
。

5. Stop and ship

5. Stop and ship

Agreed: APPROVE on the current behavior diff, no blocker or should open, no concern of your own. Stuck: an item stays disputed after two replies, or budget ends. Show both sides in 2-3 lines each. The user decides. Budget end is not approval.
Do not push during the loop. Push after agreement only if the user asked to push, ship, or update the PR. If you push to a PR, add above the model blurb:
Reviewed with sol-loop: <N> rounds with <model>. Sol verdict: approved
.
Add
on <effort>
only if verified.
Report: rounds, model, what Sol changed, diff size before/after, fixed and declined findings with reasons, usage if exposed (else say not), pushed or not.
达成一致:对当前 behavior diff 给出 APPROVE,不存在未解决的 blocker 或 should,且你自己也没有未解决的顾虑。陷入僵局:某项在两次回复后仍有争议,或预算耗尽。双方观点各用 2~3 行展示。由用户决定。预算耗尽不代表批准。
循环期间不要 push。仅当用户要求 push、ship 或更新 PR 时,达成一致后再 push。如果 push 到 PR,请在 model blurb 上方添加:
Reviewed with sol-loop: <N> rounds with <model>. Sol verdict: approved
仅在已验证的情况下添加
on <effort>
。
报告:轮数、model、Sol 做了哪些修改、修改前后的 diff 大小、已修复和已拒绝的 findings 及其原因、接口提供时的 usage(否则说明未提供),以及是否 push。