rate-fix-loop

name	rate-fix-loop
description	Drive a public web surface from baseline to ≥9.5/10 via iterated 3-seat thinktank council rounds. Each round: read verdicts → pick #1 highest-leverage actionable fix → ship → dispatch next round. Validated on 3 pages (news 9.77, benchmarks 8.0 stopped, knowledge-hub 9.73). Default: delegate to a general-purpose subagent.

Rate-fix loop

Drives a public web page from a baseline thinktank rating to ≥9.5/10 via iterated rounds of council critique + targeted fixes. Validated pattern:

• /news (Intelligence) — 7 rounds, 9.77/10, inline orchestration
• /benchmarks/compression — 4 rounds, 8.0/10, stopped on operator-action (needs real benchmark harness data, can't go higher with code alone)
• /products/knowledge-hub — 6 rounds, 9.73/10, subagent-driven, built the entire page from zero in 4 commits

When to use

• Public surface that doesn't have an obvious owner of "what makes this 10"
• 3+ defensible directions could each improve credibility
• You have ≥1 hour of clear focus to iterate (or willing to delegate to a subagent for ~30-60 min wall)

When NOT to use

• The page already has a focused product-owner with strong taste — they'll override the council anyway
• The page is shipping THIS HOUR and needs polish, not rebuild
• You're at <80% of target rating and lack 4+ hours of iteration budget

Default: delegate to subagent

Inline orchestration burns ~150-300 token-thousands per round. With 5-7 rounds typical, that's 1-2M tokens for a single page in the orchestrator context. Default pattern: dispatch a general-purpose subagent at sonnet tier to run the loop end-to-end. The orchestrator only re-enters on convergence, operator blocker, or council split.

Inline orchestration is OK when:

• First time running this pattern on a new page (you want to learn its quirks before delegating)
• The page is high-stakes enough that direct involvement matters
• You're confident the loop will converge in ≤3 rounds

The dispatch script

Lives at /c/Users/you/.claude/skills/rate-fix-loop/dispatch_tt_rating.sh. Fires 3 seats in parallel (codex gpt-5.5 + droid claude-opus-4-7 + gemini-3-flash [dead post-2026-06-18; substitute agy seat via agy_dispatch.sh]) against a question file at /tmp/review_task_<NAME>.md. Wall time ~7 min for 3-seat dispatch.

The script handles:

• PowerShell wrappers for codex/gemini/droid (avoids WSL ESM bugs)
• the codex headless wrapper disables auto-loading skill junctions (avoids prompt leak)
• gemini reads from /tmp/ not .claude/ (workspace-lock workaround)
• REVIEW_TASK_NAME not NAME (avoids Windows env collision)

The loop

1. READ /tmp/review_task_<page>-rating-round{N}/{codex,droid_opus,gemini}.log
   - Parse SCORE, TOP-3 IMPROVEMENTS, CONVERGED y/n
   - Ignore seats that echoed the prompt template (router glitch — codex
     does this ~20% of dispatches; proceed with the other two)

2. CHECK STOP CONDITIONS:
   - CONVERGED: avg ≥9.5 AND ≥1 seat says "yes" → return to orchestrator
   - operator-ACTION-REQUIRED: top fix needs vendor/spending/DNS/design-taste
   - COUNCIL-SPLIT: 2-1 disagreement on direction → escalate
   - 5+ rounds without convergence in this dispatch → escalate

3. PICK #1 HIGHEST-LEVERAGE FIX that's actionable without operator blockers.
   Apply an act-vs-ask common-sense gate before proceeding.

4. SHIP:
   - Bump <web-app>/package.json version
   - 4-gate pre-push checklist per .claude/rules/api-changes.md rule 10
   - Commit + push (mind PowerShell [locale]/(unauth) quoting trap)
   - git status --short after EVERY commit to verify clean working tree
   - Verify deploy live via curl + grep for the fix marker (poll 60s/12min)

5. DISPATCH ROUND N+1:
   - Write .claude/review_task_<page>-rating-round{N+1}.md (round 2 as template)
   - cp to /tmp/
   - bash dispatch_tt_rating.sh <page>-rating-round{N+1}
   - Wait ~7 min

6. GOTO 1.

Hard rules baked into every dispatch

• DO NOT spend money. DO NOT create accounts. DO NOT modify DNS.
• DO NOT fabricate metrics (e.g. "18× less tokens" if no live comparison). Frame as "designed to deliver 5-20×" or use existing copy.
• Anonymous-byline rule: institutional voice only on any new public copy. No founder/operator/person names except in bylines on /news/* and /blog/* per the anonymous/brand-byline directive — use an anonymous or brand byline, never personal identity.
• 4-gate pre-push checklist mandatory (lint + tests + endpoint inventory + gateway version).
• Encode any new pattern that bit you (>15 min lost) as a feedback memory.

Question file template

.claude/review_task_<page>-rating-round{N}.md should have:

1. What we want from this round — 1 paragraph, why we're rating now
2. What changed since round {N-1} — concrete bullets with commit SHAs
3. What's still NOT addressed — be honest about what was deferred
4. Required reading — exact URLs the council should hit
5. Decision context — same scoring anchor every round (10 = trade-pub credibility, etc.)
6. Output format (MANDATORY) — exact anchors so the dispatch script can parse SCORE / CONVERGED / TOP-3
7. NO preamble. NO "let me check the files first." NO file edits.

Round 2 of each loop is the cleanest template once round 1 has shipped.

Convergence trajectory pattern

Validated on 3 pages:

Round	Typical avg gain	Notes
1 (baseline)	—	Expect 4-7. Council brutal honesty on raw state.
2	+0.5 to +1.5	Round 1 fixes land; usually closes a UNANIMOUS critical bug
3	+0.3 to +1.0	Second-tier fixes (UX/copy/SEO). Diminishing returns start.
4	+0.2 to +0.7	Often a STRUCTURAL gap surfaces; either ship it or stop.
5+	+0.1 to +0.5	Approaching ceiling; convergence imminent OR plateau hit

If round 4-5 is still <8.0 after good-faith fixes, the page has a structural problem code can't solve (e.g. /benchmarks needs real harness data). Stop and escalate.

Subagent return format (under 300 words)

STATUS: <converged | operator-action | split | budget>

Final score: <avg> (droid <X>, gemini <Y>, codex <Z or "echoed">)
Rounds run in this dispatch: <N>
Total rounds since baseline: <N+1>

Commits shipped (SHA + 1-line subject):
- <sha> <subject>

Deferred (council still flagged but didn't fix):
- <item>

Stop reason: <one line>

Memory encoded (if any):
- <filename>

Cross-references

• A peer-review council skill, if this project has one — the underlying council orchestrator
• An act-vs-ask common-sense-gate skill, if this project has one — gates "want me to..." patterns
• Local pre-push gate checklist (project-specific)
• Windows path-quoting trap when globbing paths into git add
• Institutional-byline rule for new public copy, if this project has one

Receipts

• 2026-05-22 09:30 UTC: subagent B converged /products/knowledge-hub at 9.73/10 in 6 total rounds (4 in subagent dispatch), built the page from zero, 4 commits, all 3 seats said CONVERGED yes
• 2026-05-22 09:00 UTC: subagent A stopped /benchmarks/compression at 8.0/10 operator-action, 4 commits (placeholder scores hidden + JSON-LD + per-row provenance + sort labels)
• 2026-05-22 ~03:00-07:00 UTC: inline orchestration converged /news at 9.77/10 in 7 rounds (rumor withdrawal + source normalizer + Method footer + diversity gate + drafter round-robin)