1---
2name: sol-loop
3description: Use when the user says "sol loop".
4---
5
6# sol-loop
7
8This is a workflow for making your code changes more correct before (or
9sometimes after) filing a pull request. tl;dr - use OpenAI's GPT Sol to review
10your code in a loop.
11
12Make the most minimal possible changes to appease the Sol reviewers. Be careful
13of scope creep and don't be scared to push back.
14
15## Budget
16
17- Default: 3 rounds total. Round 1 is full. Later rounds check only
18 changed code and open findings.
19- Extend to 5 only for security, permissions, auth, data loss, or
20 state/concurrency, while a blocker or should stays open with evidence. Or when
21 the user asks.
22- Stop early if a round returns only nits. Declined nits and comment,
23 doc, or format-only fixes need no new round.
24- One reviewer only. Sol must not start subagents or reviewers.
25- Keep a ledger: id, severity, outcome, usage if returned. Never guess it.
26
27## 1. Scope
28
29Run `git status --short`. Do not stash, discard, or include unrelated
30changes. Limit review to the change paths if they separate cleanly.
31Otherwise stop and ask.
32
33Find the base after `git fetch origin`:
34
35- PR: `gh pr view <n> --json baseRefName,headRefOid`. Check out the branch
36 only if clean. Confirm `HEAD` is the PR head, or ahead only by this
37 change. Base: `git merge-base HEAD origin/<baseRefName>`.
38- Local: `git merge-base HEAD origin/<default-branch>`. No remote: a base
39 the user names, or `HEAD` for uncommitted changes only.
40
41The change is base to working tree in those paths, with untracked files.
42Use one diff command all rounds. State intent and out-of-scope in 1-2
43sentences. Run covering checks. Do not send code this change breaks. Note
44missing or pre-failing checks in the brief.
45
46## 2. Start Sol
47
48In T3, call `orchestrator_capabilities`. Pick the latest Sol unless the user
49named a version. Do not hardcode an ID. Record provider, model, and effort
50only if exposed. Use `delegate_task` every round (`role: "review"`,
51`mode: "async"`). Save `taskId`. New `clientRequestId` per round.
52`childThreadId` is storage, not the next target. Do not use
53`t3_thread_send`, `create_threads`, or `t3_thread_launch` for review.
54
55If T3 tools are not listed, try one direct capability call. Outside T3, use
56a native Sol subagent and keep its ID. In Claude Code, use a custom subagent
57only if it is set up to run Sol. If no route runs Sol, report the blocker. Do
58not substitute a model.
59
60Do not edit scoped files while review runs. Wait for the notice. Do not
61poll or start a second reviewer. Timeout, error, or no reply is not
62approval. On failure, cancel, verify stop, restart with the ledger.
63
64Round 1 brief (T3 children get no history):
65
66```
67Review only. Do not edit, commit, push, comment on PRs, or start subagents.
68Repo: <abs path> Base: <sha> Intent: <intent> Out of scope: <scope> Checks: <results>
69See: git diff <base> [-- <paths>]; git status --short (read untracked).
70Read surrounding code. Find bugs, broken callers, mismatch with intent.
71Skip style unless it hides a bug. Hold to the smallest change. Flag code,
72tests, or guards the intent does not need. Other paths, rare cases, small
73perf, extra compat: nits.
74blocker = intended case wrong. should = real bug callers will hit, in intent. nit = rest.
75Reply:
76VERDICT: APPROVE or CHANGES
77S1 [blocker|should|nit] <file>:<line> <claim>. Fix: <suggestion> (stable ids)
78```
79
80## 3. Answer findings
81
82Check each finding and severity yourself. Another path, rare case, or
83small cost is a nit, whatever label it came with.
84
85- Agree: smallest fix. Prefer delete or narrow over new lock, cache,
86 helper, or option. Fix the case that happened. Add one focused test
87 that fails without the fix, if intent needs it.
88- Disagree: say why, with evidence (file:line, test, output).
89- Out of scope or nit: decline in one line. List as follow-up.
90
91Update the ledger. Re-run checks and `git diff --shortstat <base>`. If
92review grew the diff, cut first. Do not agree just to end the loop.
93
94## 4. Next round
95
96Start one only if budget remains and a blocker or should is open, behavior code
97changed, or approval does not cover the current behavior diff. Use a fresh
98`delegate_task` in T3, or follow up the saved native ID. Send the round 1 brief,
99the ledger (`fixed:` / `disagree:` / `declined:` + evidence), the same base
100diff, and the change since last round. Tell Sol: open ids and changed code only.
101Mark each old id `resolved` or `still open: <reason>`.
102
103## 5. Stop and ship
104
105Agreed: APPROVE on the current behavior diff, no blocker or should open,
106no concern of your own. Stuck: an item stays disputed after two replies,
107or budget ends. Show both sides in 2-3 lines each. The user decides.
108Budget end is not approval.
109
110Do not push during the loop. Push after agreement only if the user asked
111to push, ship, or update the PR. If you push to a PR, add above the model
112blurb:
113
114`Reviewed with sol-loop: <N> rounds with <model>. Sol verdict: approved`.
115
116Add `on <effort>` only if verified.
117
118Report: rounds, model, what Sol changed, diff size before/after, fixed and
119declined findings with reasons, usage if exposed (else say not), pushed or not.