| 1 | --- |
| 2 | name: sol-loop |
| 3 | description: Use when the user says "sol loop". |
| 4 | --- |
| 5 | |
| 6 | # sol-loop |
| 7 | |
| 8 | This is a workflow for making your code changes more correct before (or |
| 9 | sometimes after) filing a pull request. tl;dr - use OpenAI's GPT Sol to review |
| 10 | your code in a loop. |
| 11 | |
| 12 | Make the most minimal possible changes to appease the Sol reviewers. Be careful |
| 13 | of 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 | |
| 29 | Run `git status --short`. Do not stash, discard, or include unrelated |
| 30 | changes. Limit review to the change paths if they separate cleanly. |
| 31 | Otherwise stop and ask. |
| 32 | |
| 33 | Find 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 | |
| 41 | The change is base to working tree in those paths, with untracked files. |
| 42 | Use one diff command all rounds. State intent and out-of-scope in 1-2 |
| 43 | sentences. Run covering checks. Do not send code this change breaks. Note |
| 44 | missing or pre-failing checks in the brief. |
| 45 | |
| 46 | ## 2. Start Sol |
| 47 | |
| 48 | In T3, call `orchestrator_capabilities`. Pick the latest Sol unless the user |
| 49 | named a version. Do not hardcode an ID. Record provider, model, and effort |
| 50 | only 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 | |
| 55 | If T3 tools are not listed, try one direct capability call. Outside T3, use |
| 56 | a native Sol subagent and keep its ID. In Claude Code, use a custom subagent |
| 57 | only if it is set up to run Sol. If no route runs Sol, report the blocker. Do |
| 58 | not substitute a model. |
| 59 | |
| 60 | Do not edit scoped files while review runs. Wait for the notice. Do not |
| 61 | poll or start a second reviewer. Timeout, error, or no reply is not |
| 62 | approval. On failure, cancel, verify stop, restart with the ledger. |
| 63 | |
| 64 | Round 1 brief (T3 children get no history): |
| 65 | |
| 66 | ``` |
| 67 | Review only. Do not edit, commit, push, comment on PRs, or start subagents. |
| 68 | Repo: <abs path> Base: <sha> Intent: <intent> Out of scope: <scope> Checks: <results> |
| 69 | See: git diff <base> [-- <paths>]; git status --short (read untracked). |
| 70 | Read surrounding code. Find bugs, broken callers, mismatch with intent. |
| 71 | Skip style unless it hides a bug. Hold to the smallest change. Flag code, |
| 72 | tests, or guards the intent does not need. Other paths, rare cases, small |
| 73 | perf, extra compat: nits. |
| 74 | blocker = intended case wrong. should = real bug callers will hit, in intent. nit = rest. |
| 75 | Reply: |
| 76 | VERDICT: APPROVE or CHANGES |
| 77 | S1 [blocker|should|nit] <file>:<line> <claim>. Fix: <suggestion> (stable ids) |
| 78 | ``` |
| 79 | |
| 80 | ## 3. Answer findings |
| 81 | |
| 82 | Check each finding and severity yourself. Another path, rare case, or |
| 83 | small 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 | |
| 91 | Update the ledger. Re-run checks and `git diff --shortstat <base>`. If |
| 92 | review grew the diff, cut first. Do not agree just to end the loop. |
| 93 | |
| 94 | ## 4. Next round |
| 95 | |
| 96 | Start one only if budget remains and a blocker or should is open, behavior code |
| 97 | changed, 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, |
| 99 | the ledger (`fixed:` / `disagree:` / `declined:` + evidence), the same base |
| 100 | diff, and the change since last round. Tell Sol: open ids and changed code only. |
| 101 | Mark each old id `resolved` or `still open: <reason>`. |
| 102 | |
| 103 | ## 5. Stop and ship |
| 104 | |
| 105 | Agreed: APPROVE on the current behavior diff, no blocker or should open, |
| 106 | no concern of your own. Stuck: an item stays disputed after two replies, |
| 107 | or budget ends. Show both sides in 2-3 lines each. The user decides. |
| 108 | Budget end is not approval. |
| 109 | |
| 110 | Do not push during the loop. Push after agreement only if the user asked |
| 111 | to push, ship, or update the PR. If you push to a PR, add above the model |
| 112 | blurb: |
| 113 | |
| 114 | `Reviewed with sol-loop: <N> rounds with <model>. Sol verdict: approved`. |
| 115 | |
| 116 | Add `on <effort>` only if verified. |
| 117 | |
| 118 | Report: rounds, model, what Sol changed, diff size before/after, fixed and |
| 119 | declined findings with reasons, usage if exposed (else say not), pushed or not. |