fix-review
Skill42 starsChanged 4 months agoApache-2.0View on GitHub
Multi-model PR review with parallel fan-out. Three Ollama models (Cloud `:cloud` by default, local fallback) review the full PR diff in parallel; Claude acts as Arbiter, using vote count as a confidence prior to confirm/escalate/dismiss findings, then applies a single consolidated fix commit. Auto-merges (squash) when no fixes were reverted and the PR is mergeable; otherwise leaves it for manual review. Usage: /fix-review [PR-number]
- Reads credentials
- Commits and pushes
11 other projects use a version of this.
Adopted by
Most recently taken up by
- AtilaMedeiros/skillstheir own version, first seen Nov 16, 2026
- AhmedMerza/claude-skillstheir own version, first seen Nov 1, 2026
- nadavnaveh/skillstheir own version, first seen Nov 1, 2026
- AhmedMerza/agent-skillstheir own version, first seen Nov 1, 2026
- allanninal/claude-code-skillstheir own version, first seen Oct 17, 2026
- xfstudio/skillstheir own version, first seen Oct 13, 2026
Used with
Projects with it also use review.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
SentrySkillreview
Fixture review skill.
Also in 3 projects that use this
Other versions11 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 11
- 0x-Shashi/WEB3-AUDIT-SKILLS★ 61same name
- lacymorrow/paperclip-hub★ 15same name
- xfstudio/skills★ 9same name
- nadavnaveh/skills★ 3same name
- AhmedMerza/agent-skills★ 2same name
- AhmedMerza/claude-skills★ 2same name
- ai4brands-design/claude-skills★ 2same name
- allanninal/claude-code-skills★ 1same name
- AtilaMedeiros/skills★ 1same name
- orbit-collective/orbit-skills★ 1same name
1 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository12 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- apply-dreamingSkill
- debugSkill
- doubt-driven-developmentSkill
- find-bugsSkill
- grill-meSkill
- housekeepingSkill
- improveSkill
- revivalSkill
- self-learnSkill
- session-endSkill
- shipSkill
The file
We split this skill into the rules it gives an agent
11 rules. 0 are common, 4 are distinctive, and 7 are very specific to this project.
0
Common
Most of the 11 edited versions we read keep these.
4
Distinctive
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 30
Only provider: Ollama (Cloud by default — :cloud models, free tier — or local via reviewer_set: local in config.yaml).
- Distinctive: line 56
If a session ever ends up doing merge before telemetry (off the canonical order), still do both: write telemetry first, then summary.
- Distinctive: line 63
If a PR number was given as argument, use it.
- Very specific: line 119
If yq is not available, fall back to grep/awk.
- Very specific: line 229
When DIFF_TYPE=docs, load the docs-specific prompt:
- Distinctive: line 466
If a round errored: 0 findings — don't retry.
- Very specific: line 509
If TOTAL_FINDINGS == 0: skip to arbiter independent scan (Step 5 still runs).
- Very specific: line 515
Read $RUN_DIR/aggregated.json.
- Very specific: line 529
Chunk dedup key: if session_id absent from JSONL, must fall back to filename stem (not panic or empty string)
- Very specific: line 557
No Makefile yet. When a Makefile is added with build:, vet:, test: targets, switch to make build && make vet && make test.
- Distinctive: line 572
Do not revert. Do not silently pass.
“Common” is measured: kept by at least 6 in 10 of the 11 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Skill: /fix-review (parallel)
session-indexer — Automated PR Review
OVERVIEW
Three model rounds run in parallel, then a single Claude arbiter round adjudicates and applies the consolidated fix.
┌─→ Round 1 (model A) ┐
diff ───┼─→ Round 2 (model B) ┼─→ aggregate (dedupe + vote count)
└─→ Round 3 (model C) ┘
↓
Arbiter (Claude) — rules + ONE fix → commit → pushWhy parallel:
- Wall time is
max(t₁, t₂, t₃)instead oft₁ + t₂ + t₃. - Three independent perspectives on the same diff (no caching effect).
- Vote count (1/3, 2/3, 3/3) is a strong confidence signal for the arbiter.
- One fix commit instead of four → cleaner PR history.
Only provider: Ollama (Cloud by default — :cloud models, free
tier — or local via reviewer_set: local in config.yaml).
OpenRouter was removed 2026-05-30 after it went pay-only.
Merge: auto-merge (squash + delete branch) when the run is clean.
"Clean" means no fixes were reverted, the PR has no merge conflicts, and
local gates either passed or only failed in layers this PR doesn't touch
(diff-scope rule). If anything blocks merge, the skill asks the user once
before acting. Caller (/ship or you) doesn't need to merge separately.
RUN COMPLETION CONTRACT (do not skip)
The canonical step order is Step 9 (Telemetry) → Step 10 (Merge) → Step 11 (Summary). A run is not complete until both of these have run:
- Step 9 telemetry —
telemetry.jsonlappended with one row per model round + one arbiter row. - Step 11 final summary — printed to the user.
Step 10 (auto-merge) is not the end of the run. Whatever Step 10
returns — merged, merged (forced), left open, or closed —
control MUST flow into Step 11 and print the summary.
If a session ever ends up doing merge before telemetry (off the canonical order), still do both: write telemetry first, then summary.
STEP 0: Resolve PR + Load Config
If a PR number was given as argument, use it.
Otherwise detect from the current branch:
PR_NUMBER="${1:-$(gh pr view --json number --jq '.number' 2>/dev/null)}"
[ -z "$PR_NUMBER" ] && { echo "No open PR. Pass /fix-review <number>"; exit 1; }
gh pr view "$PR_NUMBER" --json number,title,headRefName,baseRefName,url
BASE_BRANCH=$(gh pr view "$PR_NUMBER" --json baseRefName --jq '.baseRefName')Load config.yaml from this skill's directory. Extract:
provider(alwaysollama)reviewer_set(cloud→reviewers.ollama_cloud,local→reviewers.ollama_local)reviewers.{ollama_cloud|ollama_local}.round_{1,2,3}.modelollama_api_url(cloud) orollama_api_url_localpost_summary_to_prtelemetry_enabled,telemetry_file
PROVIDER=ollama # only provider — config.yaml `provider:` field is documentation-only
REVIEWER_SET=$(grep '^reviewer_set:' .claude/skills/fix-review/config.yaml | awk '{print $2}')
REVIEWER_SET="${REVIEWER_SET:-cloud}"Load API credentials and helpers:
source .claude/skills/lib/env.sh
source .claude/skills/lib/rest.sh
if [ "$REVIEWER_SET" = "cloud" ]; then
REVIEWER_BLOCK=ollama_cloud
load_env_key OLLAMA_API_KEY
API_KEY="$OLLAMA_API_KEY"
API_URL=$(grep '^ollama_api_url:' .claude/skills/fix-review/config.yaml | awk '{print $2}')
else
REVIEWER_BLOCK=ollama_local
API_KEY="" # local Ollama does not require auth
API_URL=$(grep '^ollama_api_url_local:' .claude/skills/fix-review/config.yaml | awk '{print $2}')
fi
# CRITICAL: export API_KEY before any background jobs (&).
# Background subshells do NOT inherit bash functions (load_env_key etc.),
# but they DO inherit exported variables. Without this export, API_KEY
# is empty in every round and all Ollama Cloud calls return 401.
export API_KEYLoad model names:
MODEL_R1=$(yq -r ".reviewers.${REVIEWER_BLOCK}.round_1.model // \"\"" .claude/skills/fix-review/config.yaml)
MODEL_R2=$(yq -r ".reviewers.${REVIEWER_BLOCK}.round_2.model // \"\"" .claude/skills/fix-review/config.yaml)
MODEL_R3=$(yq -r ".reviewers.${REVIEWER_BLOCK}.round_3.model // \"\"" .claude/skills/fix-review/config.yaml)If yq is not available, fall back to grep/awk.
Probe Ollama Cloud + external-agent failover (only when REVIEWER_SET=cloud):
ACTIVE_PROVIDER=ollama # "ollama" | "external_agents"
FAILOVER_TIER="" # "" | "external_agents"
FAILOVER_REASON=""
probe_provider() {
local payload resp http err
payload=$(jq -n --arg m "$MODEL_R1" \
'{model:$m,messages:[{role:"user",content:"OK"}],stream:false,max_tokens:3}')
resp=$(curl -s --max-time 10 -w '\n%{http_code}' \
-H "Content-Type: application/json" \
${API_KEY:+-H "Authorization: Bearer $API_KEY"} \
-d "$payload" "$API_URL")
http="${resp##*$'\n'}"
resp="${resp%$'\n'*}"
if [ "$http" -lt 200 ] || [ "$http" -ge 300 ]; then
err=$(printf '%s' "$resp" | jq -r '
if type == "object" then
(.error | if type == "string" then . elif type == "object" then .message // tostring else tostring end)
else . end // ""
' 2>/dev/null)
FAILOVER_REASON="HTTP ${http}${err:+: ${err}}"
return 1
fi
return 0
}
# External-agent tier (own free tiers, independent of Ollama quota) —
# optional, like the old cli block: an absent config key means there is
# nothing to fail over to and a cloud outage aborts the run instead.
# yq is the primary check; grep/awk fallback keeps Step 0 working on
# hosts without yq (matching the yq-less fallback the script already
# documents for the model-name reads a few lines below).
EXTERNAL_AGENTS_EXIST="no"
if command -v yq >/dev/null 2>&1; then
yq -e '.reviewers.external_agents' .claude/skills/fix-review/config.yaml >/dev/null 2>&1 \
&& EXTERNAL_AGENTS_EXIST="yes"
elif grep -q '^ external_agents:' .claude/skills/fix-review/config.yaml 2>/dev/null; then
EXTERNAL_AGENTS_EXIST="yes"
fi
if [ "$REVIEWER_SET" = "cloud" ] && ! probe_provider; then
if [ "$EXTERNAL_AGENTS_EXIST" = "yes" ]; then
echo "⚠️ FAILOVER: Ollama Cloud unavailable (${FAILOVER_REASON}) — engaging external_agents tier" >&2
ACTIVE_PROVIDER=external_agents
FAILOVER_TIER=external_agents
else
echo "✗ Ollama Cloud unavailable (${FAILOVER_REASON}) and no external_agents tier configured — aborting." >&2
exit 1
fi
fiTelemetry helpers:
TELEMETRY_ENABLED=$(grep '^telemetry_enabled:' .claude/skills/fix-review/config.yaml | awk '{print $2}')
TELEMETRY_FILE=$(grep '^telemetry_file:' .claude/skills/fix-review/config.yaml | awk '{print $2}')
TELEMETRY_ENABLED="${TELEMETRY_ENABLED:-true}"
TELEMETRY_FILE="${TELEMETRY_FILE:-.claude/skills/fix-review/telemetry.jsonl}"
now_ms() {
date +%s%3N 2>/dev/null \
|| echo $(($(date +%s) * 1000))
}STEP 1: Build the Review Prompt
Get the full PR diff. -U10 widens context per hunk to 10 lines.
DIFF=$(gh pr diff "${PR_NUMBER}")Detect diff type
is_docs_only_diff() {
local files
files=$(gh pr diff "${PR_NUMBER}" --name-only)
[ -z "$files" ] && return 1
while IFS= read -r f; do
case "$f" in
*.md|*.markdown|*.rst|*.adoc) ;;
docs/*) ;;
README*|CHANGELOG*|LICENSE*|CONTRIBUTING*) ;;
CODE_OF_CONDUCT*|SECURITY*|AUTHORS*) ;;
CLAUDE.md|AGENTS.md|GEMINI.md) ;;
*.yaml|*.yml|*.toml) ;;
.env*|*/.env*) ;;
.gitignore|.editorconfig|.dockerignore) ;;
*) return 1 ;;
esac
done <<< "$files"
return 0
}
DIFF_TYPE=code
if is_docs_only_diff; then
DIFF_TYPE=docs
echo "→ Documentation-only diff detected — using docs-prompt.txt"
fiWhen DIFF_TYPE=docs, load the docs-specific prompt:
if [ "$DIFF_TYPE" = "docs" ]; then
DOCS_PROMPT_FILE=".claude/skills/fix-review/docs-prompt.txt"
[ ! -f "$DOCS_PROMPT_FILE" ] && DOCS_PROMPT_FILE="$HOME/.claude/skills/fix-review/docs-prompt.txt"
if [ -f "$DOCS_PROMPT_FILE" ]; then
PROMPT_TEMPLATE=$(cat "$DOCS_PROMPT_FILE")
else
DIFF_TYPE=code
fi
fiFor DIFF_TYPE=docs: build PROJECT_CONTEXT from head -150 CLAUDE.md and substitute
both {PROJECT_CONTEXT} and {DIFF} placeholders.
Prompt template (default, DIFF_TYPE=code; substitute $DIFF inline):
You are a senior Go engineer reviewing a pull request in **session-indexer**, a
single Go 1.26 binary (pure Go, no CGO) with four subcommands: mine, embed,
search, stats. It indexes Claude Code JSONL sessions into a per-project SQLite
database (modernc.org/sqlite, WAL mode, FTS5) and retrieves them via
embedding-first cosine similarity (bge-m3 via Ollama, 1024-dim float32 BLOBs)
with FTS5 BM25 fallback. Layout: cmd/session-indexer/main.go (Cobra root),
internal/db/ (schema + open), internal/mine/ (parse → chunk → store → embed),
internal/embed/ (Ollama REST client), internal/search/ (cosine + FTS5).
Review the following git diff using the Code Review Pyramid — evaluate from
bottom to top, spending the most attention on the lower layers and less on
the higher ones:
5 (top) — Code style → DO NOT FLAG. gofmt + go vet handle this.
4 — Tests → Table-driven _test.go files. Critical paths
covered: JSONL parsing, chunking, noise filter,
embedding probe fallback, cosine similarity,
FTS5 keyword search. Race-friendly (go test -race
must pass). Regression tests for edge cases
(binary tool_result, empty session, etc.).
3 — Documentation → Exported APIs documented. Non-obvious logic
(binary heuristic, chunking rules, schema
version check) explained briefly.
2 — Implementation → Bugs, error wrapping (fmt.Errorf("...%w", err)),
nil deref, missing defer rows.Close() /
resp.Body.Close(), unhandled SQLite errors,
float32 BLOB length check (len(blob) % 4 == 0
and len(blob) == 4096 for bge-m3), Ollama probe
timeout respected (2s for GET /api/tags),
tool_result binary heuristic correctness
(len > 10240 || base64 regex match),
chunk dedup key stability (session_id fallback
to filename stem when absent from JSONL),
INSERT OR IGNORE idempotency on re-mine,
FTS5 trigger sync (chunks_ai / chunks_ad),
WAL busy_timeout=5000 set on every DB open.
1 (base) — API / Architecture → Schema version check on every DB open (must
return wrapped error on mismatch — not panic),
per-project DB isolation (no hardcoded paths —
DB path always from --db flag), noise filter
thresholds match spec (<30 chars, XML/HTML
prefix, slash-command prefix), chunking at
paragraph boundary (not mid-word), cosine
exhaustive over ALL embeddings rows (no subset
sampling), Ollama probe failure must be non-
fatal (warn + continue without embeddings).
Return ONLY a JSON array — no prose, no markdown fences, just the raw JSON.
Each item must have exactly these fields:
"file" — relative file path (string)
"line" — line number on the + side of the diff (integer)
"layer" — pyramid layer number 1–4 (integer)
"severity" — one of: "error", "warning", "suggestion" (string)
"body" — clear description of the issue and how to fix it (string)
Severity guide:
error — must fix before merge (bug, race, layer-1 violation)
warning — should fix (missing test for critical path, undocumented public API)
suggestion — nice to have (minor clarity improvement)
Do NOT flag: gofmt issues, import order, blank lines (layer 5 — automated).
Do NOT flag code not present in this diff.
Do NOT propose architectural rewrites; focus on what the diff actually changes.
If there are no issues, return an empty array: []
Git diff:
---
{DIFF}
---Hold the prompt template in a shell variable, e.g. PROMPT_TEMPLATE,
then substitute {DIFF} per-call:
PROMPT=$(printf '%s' "$PROMPT_TEMPLATE" | sed "s|{DIFF}|$(printf '%s' "$DIFF" | sed 's/[\\/&]/\\&/g')|")STEP 2: Fan Out — Three Models in Parallel
RUN_DIR=$(mktemp -d -t fix-review-XXXX)
WALL_START_MS=$(now_ms)
REVIEW_SYSTEM_MSG="You are a senior code reviewer. Your entire response MUST be a raw JSON array — nothing else. Start with [ and end with ]. No prose, no markdown fences, no explanations before or after. If there are no issues output exactly: [] Report at most 8 findings, most severe first; each body under 30 words. Do not include informational or 'no action needed' entries — only real issues."
export PROVIDER REVIEWER_BLOCK API_URL API_KEY PROMPT RUN_DIR \
MODEL_R1 MODEL_R2 MODEL_R3 REVIEW_SYSTEM_MSG
export -f rest_post now_ms 2>/dev/null
run_round() {
local n="$1" model="$2"
local r_start r_end payload response think pt ct
r_start=$(now_ms)
think=$(yq -r ".reviewers.${REVIEWER_BLOCK}.round_${n}.think // true" \
.claude/skills/fix-review/config.yaml 2>/dev/null)
payload=$(jq -n --arg m "$model" --arg sys "$REVIEW_SYSTEM_MSG" \
--arg user "$PROMPT" --argjson think "$think" \
'{model:$m,messages:[{role:"system",content:$sys},{role:"user",content:$user}],stream:false,think:$think}')
response=$(rest_post "$API_URL" "$payload" "$API_KEY") \
|| response='{"_error":"rest_post_failed"}'
# Empty-content retry: reasoning models can return 200 + empty content
# on large diffs even with think:false. Retry once with a smaller
# num_predict cap before accepting a zero-finding round.
local content
content=$(printf '%s' "$response" | jq -r '.message.content // empty' 2>/dev/null)
if [ -n "$response" ] && [ -z "$(printf '%s' "$content" | tr -d '[:space:]')" ] \
&& ! printf '%s' "$response" | jq -e '._error' >/dev/null 2>&1; then
echo "warn: round ${n} (${model}) returned empty content — retrying once with a tighter cap" >&2
payload=$(jq -n --arg m "$model" --arg sys "$REVIEW_SYSTEM_MSG" \
--arg user "$PROMPT" --argjson think "$think" \
'{model:$m,messages:[{role:"system",content:$sys},{role:"user",content:$user}],stream:false,think:$think,options:{num_predict:2000}}')
response=$(rest_post "$API_URL" "$payload" "$API_KEY") \
|| response='{"_error":"rest_post_failed"}'
fi
r_end=$(now_ms)
printf '%s' "$response" > "$RUN_DIR/round_${n}.raw.json"
pt=$(printf '%s' "$response" | jq -r '.prompt_eval_count // empty')
ct=$(printf '%s' "$response" | jq -r '.eval_count // empty')
printf '%s\n%s\n%s %s\n' "$model" "$((r_end - r_start))" \
"${pt:-null}" "${ct:-null}" > "$RUN_DIR/round_${n}.meta"
}
source .claude/skills/lib/agents.sh
run_external_round() {
local n="$1"
local r_start r_end prompt_file
r_start=$(now_ms)
prompt_file=$(mktemp)
printf '%s\n\n%s' "$REVIEW_SYSTEM_MSG" "$PROMPT" > "$prompt_file"
if ! try_external_agents "$n" "$prompt_file" ".claude/skills/fix-review/config.yaml" "$RUN_DIR"; then
echo "✗ round ${n}: every external agent failed/empty — 0 findings" >&2
printf '[]' > "$RUN_DIR/round_${n}.raw.json"
printf 'none\n0\n' > "$RUN_DIR/round_${n}.meta"
fi
rm -f "$prompt_file"
r_end=$(now_ms)
# try_external_agents already wrote round_${n}.meta with duration "0" on
# success — fix up the timing half now the real elapsed time is known.
if [ -f "$RUN_DIR/round_${n}.failover" ]; then
local winning_tool; winning_tool=$(head -1 "$RUN_DIR/round_${n}.meta")
printf '%s\n%s\n' "$winning_tool" "$((r_end - r_start))" > "$RUN_DIR/round_${n}.meta"
fi
}
export -f run_round run_external_round rest_post now_ms run_external_agent \
try_external_agents agent_cursor_agent agent_omp agent_codex agent_opencode agent_kilo
if [ "$ACTIVE_PROVIDER" = "external_agents" ]; then
run_external_round 1 &
run_external_round 2 &
run_external_round 3 &
wait
NUM_ROUNDS=3
else
run_round 1 "$MODEL_R1" &
run_round 2 "$MODEL_R2" &
run_round 3 "$MODEL_R3" &
wait
NUM_ROUNDS=3
fi
WALL_END_MS=$(now_ms)
WALL_TIME_MS=$((WALL_END_MS - WALL_START_MS))If
export -fdoesn't propagate (older bash, restricted shells), inline therun_round/run_external_roundbodies insidebash -c '...' &blocks. Contract: each background job writesround_N.raw.json+round_N.meta(Ollama rounds: 3 lines —model\nduration_ms\nprompt_tokens completion_tokens; external_agents rounds: 2 lines —tool\nduration_ms, no token counts since these tools don't report them).Failover chain: unlike per-round cascading, session-indexer decides
ACTIVE_PROVIDERonce for the whole run at Step 0 (a single upfront probe, not per-round) — if cloud is down, all three rounds go throughtry_external_agents, which walksreviewers.external_agentsin config order and keeps the first tool that returns non-empty output. Each round cascades independently starting from the same tool[0], so a full outage can converge all three rounds onto the same external tool — degraded diversity, but still a real review instead of zero coverage.
STEP 3: Parse Each Response → Tagged Findings
parse_round() {
local n="$1"
local model content
model=$(head -1 "$RUN_DIR/round_${n}.meta")
if [ "$ACTIVE_PROVIDER" = "external_agents" ]; then
# try_external_agents already unwraps each tool's own output envelope —
# round_${n}.raw.json holds plain extracted text, not an Ollama
# {"message":{"content":...}} wrapper.
content=$(cat "$RUN_DIR/round_${n}.raw.json")
else
content=$(jq -r '.message.content // empty' "$RUN_DIR/round_${n}.raw.json")
fi
content=$(printf '%s' "$content" | sed -E 's/^```(json)?[[:space:]]*//; s/```[[:space:]]*$//')
if ! echo "$content" | jq -e 'type == "array"' >/dev/null 2>&1; then
echo "warn: round ${n} (${model}) returned non-array — counting 0 findings" >&2
echo "[]" > "$RUN_DIR/round_${n}.findings.json"
return
fi
echo "$content" | jq --arg m "$model" 'map(. + {model: $m})' \
> "$RUN_DIR/round_${n}.findings.json"
}
for n in $(seq 1 "$NUM_ROUNDS"); do parse_round "$n"; doneIf a round errored: 0 findings — don't retry.
STEP 4: Aggregate — Dedupe + Vote Count
Merge all rounds. Group by (file, line). Record votes, models, longest body,
worst severity, lowest layer.
jq -s '
flatten
| group_by(.file + ":" + (.line|tostring))
| map({
file: .[0].file,
line: .[0].line,
votes: length,
models: [.[] | .model],
bodies: [.[] | .body],
body: ([.[] | .body] | sort_by(length) | last),
severity: ([.[] | .severity] | unique
| (if any(. == "error") then "error"
elif any(. == "warning") then "warning"
else "suggestion" end)),
layer: ([.[] | .layer] | min)
})
| sort_by(.layer,
(if .severity == "error" then 0
elif .severity == "warning" then 1
else 2 end),
-.votes)
' "$RUN_DIR"/round_*.findings.json > "$RUN_DIR/aggregated.json"
TOTAL_FINDINGS=$(jq 'length' "$RUN_DIR/aggregated.json")
declare -A VOTE_BAND
for v in $(seq 1 "$NUM_ROUNDS"); do
VOTE_BAND[$v]=$(jq --argjson v "$v" '[.[] | select(.votes == $v)] | length' "$RUN_DIR/aggregated.json")
done
TOP_VOTE_COUNT="${VOTE_BAND[$NUM_ROUNDS]:-0}"Sorted critical-first: layer 1 errors 3/3 votes → layer 4 suggestions 1/3.
If TOTAL_FINDINGS == 0: skip to arbiter independent scan (Step 5 still runs).
STEP 5: Arbiter (Claude)
Read $RUN_DIR/aggregated.json. For each finding, rule:
| Ruling | When |
| CONFIRM | Real issue. Default for votes ≥ 2 unless clearly false-positive. |
| ESCALATE | Real issue, more severe than tagged. |
| DISMISS | False positive, conflicts with project rules, or layer-5 noise. Default for votes == 1 unless obviously real. |
| DEFER | Real but out of scope for this PR. Log, don't fix. |
Vote count is a confidence prior, not a verdict.
Independent scan of the full diff — flag anything all three models missed. Pay special attention to session-indexer specifics:
- JSONL parsing: tool_result binary heuristic (
len > 10240 || base64 regex) — off-by-one or regex anchor bugs - Chunk dedup key: if
session_idabsent from JSONL, must fall back to filename stem (not panic or empty string) - Ollama probe failure:
GET /api/tags2s timeout; failure must logwarn: ollama unavailableand continue without embeddings — not block or panic - FTS5 trigger sync:
chunks_ai/chunks_adtriggers must fire on every INSERT/DELETE — check trigger definitions in schema.sql - Schema version check:
db.QueryRow("SELECT value FROM meta WHERE key='schema_version'")must return a wrapped error on mismatch — not panic, not silent continue - Float32 BLOB:
encoding/binaryLittleEndian; must validatelen(blob) == 4096(1024 × 4 bytes) before cosine to avoid NaN - WAL busy_timeout:
PRAGMA busy_timeout=5000must be set on every DB open path (concurrent Stop hooks can deadlock otherwise) - Per-project isolation: DB path always from
--dbflag — no default hardcoded to project root
Apply CONFIRM + ESCALATE fixes via the Edit tool. Minimal change per fix; no opportunistic refactoring.
Save rulings to $RUN_DIR/arbiter.json:
[
{"file":"...", "line":42, "ruling":"CONFIRM", "votes":3, "body":"..."},
...
]STEP 6: Run Quality Gates
go build ./... 2>&1 | tail -20
go vet ./... 2>&1 | tail -20
go test -race ./... 2>&1 | tail -30No Makefile yet. When a Makefile is added with build:, vet:, test: targets,
switch to make build && make vet && make test.
Diff-scope check before reverting
- Check what files this PR touches —
gh pr diff "${PR_NUMBER}" --name-only. - Map failure to layer:
go build/go vet/go test -race→ only from.gofile changes.- Schema / FTS5 trigger test → only if
internal/db/schema.sqlchanged. - SQLite WAL / concurrent hook test → only if
internal/db/orinternal/mine/changed.
- Decide:
- Failing layer touched by diff → identify which fix broke it, revert, log as
reverted — caused build/test failure, re-run gates. - Failing layer not touched → mark as pre-existing. Log in summary. Do not revert. Do not silently pass.
- Failing layer touched by diff → identify which fix broke it, revert, log as
A docs/skill-only PR (.claude/, *.md) cannot cause Go build failures by construction.
GATES_OK=no
# ... run gates, then if pass-clean or all-pre-existing-skip:
# GATES_OK=yesSTEP 6a: Compute Aggregates Before Output
SEQ_SUM_MS=0
for n in $(seq 1 "$NUM_ROUNDS"); do
meta="$RUN_DIR/round_${n}.meta"
[ -f "$meta" ] || continue
d=$(sed -n '2p' "$meta")
SEQ_SUM_MS=$((SEQ_SUM_MS + ${d:-0}))
done
SPEEDUP=$(awk -v s="$SEQ_SUM_MS" -v w="$WALL_TIME_MS" \
'BEGIN{ if (w>0) printf "%.2f", s/w; else print "n/a" }')
if [ "$ACTIVE_PROVIDER" = "external_agents" ]; then
# Read back whichever tool actually won each round — round_N.meta line 1
# (set by try_external_agents / run_external_round's fallback). A round
# that fully failed gets a placeholder rather than the literal "none"
# string (which would otherwise show up in the summary as a "tool").
MODELS_LIST=""
for n in $(seq 1 "$NUM_ROUNDS"); do
[ -n "$MODELS_LIST" ] && MODELS_LIST+=" | "
t=$(head -1 "$RUN_DIR/round_${n}.meta" 2>/dev/null)
if [ "$t" = "none" ] || [ -z "$t" ]; then
MODELS_LIST+="(failed)"
else
MODELS_LIST+="$t"
fi
done
else
MODELS_LIST=""
for n in $(seq 1 "$NUM_ROUNDS"); do
[ -n "$MODELS_LIST" ] && MODELS_LIST+=" | "
v="MODEL_R${n}"
MODELS_LIST+="${!v}"
done
fi
VOTE_BAND_REPORT=""
for v in $(seq "$NUM_ROUNDS" -1 1); do
count="${VOTE_BAND[$v]:-0}"
[ "$count" -eq 0 ] && continue
tag=""
[ "$v" = "$NUM_ROUNDS" ] && tag=" (unanimous)"
[ "$v" = 1 ] && tag=" (low confidence)"
VOTE_BAND_REPORT+=" ${v}/${NUM_ROUNDS} votes: ${count}${tag}"$'\n'
done
[ -z "$VOTE_BAND_REPORT" ] && VOTE_BAND_REPORT=" (no findings)"
FAILOVER_SECTION=""
if [ -n "$FAILOVER_TIER" ]; then
# List each round's winning tool, skipping fully-failed rounds (their
# meta line 1 is "none") and deduping so a 3-round cascade onto the
# same tool is shown as e.g. "omp x3" rather than just "omp" —
# matches MODELS_LIST's per-round fidelity in the summary above.
round_tools=""
for n in $(seq 1 "$NUM_ROUNDS"); do
t=$(head -1 "$RUN_DIR/round_${n}.meta" 2>/dev/null)
if [ "$t" != "none" ] && [ -n "$t" ]; then
round_tools+="$t"$'\n'
fi
done
agents_csv=$(printf '%s' "$round_tools" | awk '
NF { if (!seen[$0]++) order[++c]=$0; cnt[$0]++ }
END {
for (i=1; i<=c; i++) printf "%s%s x%d", (i==1?"":", "), order[i], cnt[order[i]]
print ""
}
')
[ -z "$agents_csv" ] && agents_csv="(no tool returned output)"
FAILOVER_SECTION=$(cat <<EOF
### ⚠️ Provider failover
Primary provider (ollama / Ollama Cloud) was unavailable.
Tier used: ${FAILOVER_TIER}
Reason: ${FAILOVER_REASON}
Agents: ${agents_csv}
Action: regenerate OLLAMA_API_KEY at https://ollama.com/settings/keys
or adjust reviewers.external_agents in config.yaml.
EOF
)
fi
CONFIRMED_COUNT=$(jq '[.[] | select(.ruling=="CONFIRM")] | length' "$RUN_DIR/arbiter.json")
ESCALATED_COUNT=$(jq '[.[] | select(.ruling=="ESCALATE")] | length' "$RUN_DIR/arbiter.json")
DISMISSED_COUNT=$(jq '[.[] | select(.ruling=="DISMISS")] | length' "$RUN_DIR/arbiter.json")
DEFERRED_COUNT=$( jq '[.[] | select(.ruling=="DEFER")] | length' "$RUN_DIR/arbiter.json")
ADDED_NEW_COUNT=$(jq '[.[] | select(.added_new == true)] | length' "$RUN_DIR/arbiter.json")
PR_URL=$(gh pr view "$PR_NUMBER" --json url --jq '.url')Reference these names — and only these — in Steps 7-10. Naming canon: SEQ_SUM_MS.
STEP 7: Single Commit + Push
git add -A
git restore --staged .claude/skills/fix-review/telemetry.jsonl 2>/dev/null || true
if [ "$(git diff --cached --name-only | wc -l)" -eq 0 ]; then
echo "No fixes applied — nothing to commit."
COMMIT_SHA="(no-op)"
else
git commit -m "fix(pr#${PR_NUMBER}): address /fix-review findings
$(jq -r '.[] | select(.ruling == "CONFIRM" or .ruling == "ESCALATE")
| "- \(.file):\(.line) — \(.body | gsub("\n"; " ") | .[0:80])"' \
"$RUN_DIR/arbiter.json" | head -20)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>"
git push
COMMIT_SHA=$(git rev-parse --short HEAD)
fiSTEP 8: Optional PR Summary Comment
If post_summary_to_pr: true:
gh pr comment "$PR_NUMBER" --body "$(cat <<EOF
<details>
<summary>/fix-review — ${PROVIDER} parallel pass · ${TOTAL_FINDINGS} findings · ${CONFIRMED_COUNT} fixed · ${DISMISSED_COUNT} dismissed</summary>
Wall time: ${WALL_TIME_MS} ms (vs sum-sequential ${SEQ_SUM_MS} ms — ${SPEEDUP}× speedup)
Models: ${MODELS_LIST}
Arbiter: Claude (vote count used as confidence prior)
| File:Line | Votes | Layer | Sev | Ruling |
|-----------|-------|-------|-----|--------|
$(jq -r --argjson n "$NUM_ROUNDS" '.[] | "| \(.file):\(.line) | \(.votes)/\($n) | L\(.layer) | \(.severity) | \(.ruling) |"' "$RUN_DIR/arbiter.json")
</details>
EOF
)"STEP 9: Telemetry — JSONL Append
Three round entries + one arbiter entry per run.
Round entry:
{
"timestamp": "2026-06-25T12:34:56Z",
"pr_number": 1,
"round_number": 1,
"model": "deepseek-v4-flash:cloud",
"provider": "ollama",
"findings_count": 3,
"prompt_tokens": 8000,
"completion_tokens": 400,
"estimated_cost_usd": null,
"duration_ms": 6200,
"parallel": true
}Arbiter entry:
{
"timestamp": "2026-06-25T12:35:10Z",
"pr_number": 1,
"round_number": "arbiter",
"model": "claude",
"provider": "local",
"confirmed": 2,
"escalated": 0,
"dismissed": 1,
"added_new": 1,
"parallel": true,
"wall_time_ms": 7800
}estimated_cost_usd is always null — Ollama Cloud free tier has no per-token billing.
COST=null
if [ "$TELEMETRY_ENABLED" = "true" ]; then
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
ROUND_PROVIDER="$ACTIVE_PROVIDER"
for N in $(seq 1 "$NUM_ROUNDS"); do
meta="$RUN_DIR/round_${N}.meta"
[ -f "$meta" ] || continue
MODEL=$(sed -n '1p' "$meta")
DURATION_MS=$(sed -n '2p' "$meta")
read PROMPT_TOKENS COMPLETION_TOKENS < <(sed -n '3p' "$meta")
FINDINGS_COUNT=$(jq 'length' "$RUN_DIR/round_${N}.findings.json")
jq -cn \
--arg ts "$TIMESTAMP" \
--argjson pr "${PR_NUMBER}" \
--argjson round "${N}" \
--arg model "$MODEL" \
--arg provider "$ROUND_PROVIDER" \
--argjson findings "${FINDINGS_COUNT}" \
--argjson ptokens "${PROMPT_TOKENS:-null}" \
--argjson ctokens "${COMPLETION_TOKENS:-null}" \
--argjson cost "${COST:-null}" \
--argjson duration "${DURATION_MS}" \
'{timestamp:$ts, pr_number:$pr, round_number:$round, model:$model,
provider:$provider, findings_count:$findings,
prompt_tokens:$ptokens, completion_tokens:$ctokens,
estimated_cost_usd:$cost, duration_ms:$duration, parallel:true}' \
>> "$TELEMETRY_FILE" 2>/dev/null \
|| echo "warn: telemetry write failed for round ${N} — continuing" >&2
done
jq -cn \
--arg ts "$TIMESTAMP" \
--argjson pr "${PR_NUMBER}" \
--arg round "arbiter" \
--arg model "claude" \
--arg provider "local" \
--argjson confirmed "${CONFIRMED_COUNT}" \
--argjson escalated "${ESCALATED_COUNT}" \
--argjson dismissed "${DISMISSED_COUNT}" \
--argjson added_new "${ADDED_NEW_COUNT}" \
--argjson wall "${WALL_TIME_MS}" \
'{timestamp:$ts, pr_number:$pr, round_number:$round, model:$model,
provider:$provider, confirmed:$confirmed, escalated:$escalated,
dismissed:$dismissed, added_new:$added_new,
parallel:true, wall_time_ms:$wall}' \
>> "$TELEMETRY_FILE" 2>/dev/null \
|| echo "warn: telemetry write failed for arbiter — continuing" >&2
fiSTEP 10: Auto-merge (or ask if blocked)
Conditions for clean auto-merge — all must hold:
- No reverts —
arbiter.jsoncontains no"reverted"rulings. - PR mergeable — no merge conflicts.
- Gates green or pre-existing-skip —
GATES_OK=yes. - Remote checks not failing —
gh pr checksshows nofail/errorrows.
MERGEABLE=$(gh pr view "$PR_NUMBER" --json mergeable --jq '.mergeable')
HAS_REVERT=$(jq -e 'any(.[]?; .ruling == "reverted")' "$RUN_DIR/arbiter.json" >/dev/null 2>&1 && echo "yes" || echo "no")
GATES_OK="${GATES_OK:-no}"
CHECKS_OUT=$(gh pr checks "$PR_NUMBER" 2>&1 || true)
if echo "$CHECKS_OUT" | grep -qE '^[a-zA-Z0-9_./-]+\s+(fail|error|cancelled)'; then
CHECKS_OK=no
else
CHECKS_OK=yes
fi
BLOCKING=()
[ "$MERGEABLE" != "MERGEABLE" ] && BLOCKING+=("PR not mergeable: ${MERGEABLE}")
[ "$HAS_REVERT" = "yes" ] && BLOCKING+=("one or more fixes reverted (gate failure caused by this PR)")
[ "$GATES_OK" != "yes" ] && BLOCKING+=("local gates failed in a layer this PR touches")
[ "$CHECKS_OK" != "yes" ] && BLOCKING+=("remote checks failing — see 'gh pr checks ${PR_NUMBER}'")
if [ ${#BLOCKING[@]} -eq 0 ]; then
if ! gh pr merge "$PR_NUMBER" --auto --squash --delete-branch 2>/dev/null; then
gh pr merge "$PR_NUMBER" --squash --delete-branch
fi
MERGE_STATUS="merged (squash)"
else
cat <<EOM
PR #${PR_NUMBER} cannot auto-merge:
$(printf ' - %s\n' "${BLOCKING[@]}")
What should I do?
1. Merge anyway (squash + delete branch)
2. Leave open — you'll handle it manually
3. Close PR — abandon
EOM
fi→ Now proceed to Step 11. Whatever Step 10 returned does not end the run.
STEP 11: Final Summary (printed)
## /fix-review (parallel) — PR #${PR_NUMBER}
Provider: ${ACTIVE_PROVIDER}
Rounds: ${NUM_ROUNDS}
Models: ${MODELS_LIST}
Wall time: ${WALL_TIME_MS} ms (sum-sequential ${SEQ_SUM_MS} ms — ${SPEEDUP}× speedup)
Aggregated findings: ${TOTAL_FINDINGS}
${VOTE_BAND_REPORT}
Arbiter:
Confirmed: ${CONFIRMED_COUNT}
Escalated: ${ESCALATED_COUNT}
Dismissed: ${DISMISSED_COUNT}
Deferred: ${DEFERRED_COUNT}
Added new: ${ADDED_NEW_COUNT}
Tests: ${TEST_RESULT}
Lint: ${LINT_RESULT}
Commit: ${COMMIT_SHA}
PR: ${PR_URL}
Merge: ${MERGE_STATUS}
Telemetry: ${TELEMETRY_FILE}
${FAILOVER_SECTION}SWITCHING REVIEWER SET
Switch between Ollama Cloud and local Ollama:
- "switch fix-review to local"
- "switch fix-review to cloud"
sed -i "s/^reviewer_set: .*/reviewer_set: {new_set}/" .claude/skills/fix-review/config.yamlOn the next run, Step 0 picks the matching reviewers.ollama_{cloud,local} block.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

