--- description: Outer orchestration loop that runs council-debate repeatedly on an artifact until N consecutive clean rounds or max rounds exceeded. category: general --- flowchart TD _HEADER_[""]:::headerStyle classDef headerStyle fill:none,stroke:none subgraph _MAIN_[" "] %% Phase 1: Setup subgraph Setup["Phase 1: Setup"] GOAL{Review Goal?} GOAL -->|Standard-based| RUBRIC[Load Rubric] GOAL -->|Accuracy-based| TRUTH[Load Source of Truth] RUBRIC --> ARTIFACT[Select Artifact] TRUTH --> ARTIFACT end %% Phase 2: Run Debate (inner module) subgraph Debate["Phase 2: Council Debate"] ARTIFACT --> DEBATE[[Run council-debate]] DEBATE --> OUTCOME{Debate Outcome?} OUTCOME -->|Fixes applied| FIXED[Fixes Applied
Round N] OUTCOME -->|No fixes needed| CLEAN[Clean Round] end %% Phase 3: Convergence Check subgraph Converge["Phase 3: Convergence Check"] FIXED --> RESET[Reset Clean Counter
to 0] CLEAN --> INC[Increment Clean Counter] RESET --> MAX{Round <= Max?} INC --> THRESH{Clean Count
>= Threshold?} THRESH -->|Yes| STEADY([Steady State]) THRESH -->|No| MAX MAX -->|Yes| DEBATE MAX -->|No| STUCK([Report Unresolved]) end %% Phase 4: Queue + Monitoring subgraph Monitor["Queue + Monitoring"] STEADY --> NEXT{More Artifacts?} STUCK --> NEXT NEXT -->|Yes| ARTIFACT NEXT -->|No| DONE([Batch Complete]) WLOG[Worklog
append-only] ~~~ REMIND[Heartbeat
10 min check] REMIND ~~~ TMUX[tmux
tail output] end click GOAL "#" "**Review Goal**\nTwo modes determine the council-debate prompt:\n\n*Standard-based:* Check artifact against a written rubric.\n- Identify or write the standard first\n- Example: `~/.claude/skills/audit-logging/reference/service-guide-standard.md`\n\n*Accuracy-based:* Check artifact for factual correctness.\n- Council reads artifact alongside ground-truth sources\n- Goal: does the document accurately describe reality?" click RUBRIC "#" "**Load Rubric**\nThe written standard the artifact must conform to.\n- Store as `.claude/rules/*.md` or inline in the prompt\n- Must have clear pass/fail criteria\n- Avoid subjective criteria -- models need unambiguous signals" click TRUTH "#" "**Load Source of Truth**\nThe authoritative reference the artifact should match:\n- Source code the docs describe\n- Config files the docs reference\n- Test output the docs claim\n- Schema the API docs specify" click ARTIFACT "#" "**Select Artifact**\nOne artifact per convergence session.\nExamples: a doc file, source module, PR diff, API spec.\n\nRule: one artifact per teammate.\nThe orchestrator manages the queue and spawns teammates -- it does not run council directly." click DEBATE "#" "**Run council-debate**\nThis is the [council-debate workflow](../council-debate/council-debate-workflow.html) running as an inner module.\n\nExecutes one full debate round:\n1. Run all reviewers in parallel (claude, gemini, codex, cursor-agent)\n2. Triage results by agreement level\n3. Apply unanimous/majority fixes\n4. Return outcome: fixes applied or clean round\n\nSee the council-debate workflow for the full debate procedure." click OUTCOME "#" "**Debate Outcome**\nAfter each council-debate round:\n- *Fixes applied:* At least one issue was fixed. Reset clean counter.\n- *No fixes needed:* All reviewers said NO ISSUES, or only minority notes logged. Increment clean counter." click FIXED "#" "**Fixes Applied**\nThe debate round found and fixed issues.\nLog to worklog:\n`[timestamp] FIXED artifact -- N issues (Round M)`\n\nNext debate round will include the fixes in its prompt so reviewers can confirm they landed correctly." click CLEAN "#" "**Clean Round**\nNo fixes were needed this round.\nThis is one step toward convergence.\n\nLog to worklog:\n`[timestamp] CLEAN artifact -- Round M (clean count: K)`" click RESET "#" "**Reset Clean Counter**\nFixes were applied, so any prior clean streak is broken.\nSet clean_count = 0.\n\nConvergence requires N *consecutive* clean rounds -- a fix in between restarts the count." click INC "#" "**Increment Clean Counter**\nNo fixes this round. clean_count += 1.\n\nDefault threshold: 2 consecutive clean rounds.\nThis confirms the first clean round was not a fluke -- a second independent debate with no new issues gives high confidence." click THRESH "#" "**Clean Count >= Threshold?**\nDefault threshold: 2 consecutive clean rounds.\n\nWhy 2? A single NO ISSUES round could be a false negative -- models might miss something on one pass. Two consecutive clean rounds from independent debate sessions is strong evidence of convergence.\n\nConfigurable: raise to 3 for critical artifacts." click MAX "#" "**Round <= Max?**\nDefault max: 3 rounds.\nPrevents infinite loops when issues keep appearing.\n\nIf round <= max: run another debate round.\nIf round > max: stop and report unresolved issues.\n\nRemaining issues after max rounds typically require human judgment." click STEADY "#" "**Steady State**\nN consecutive clean rounds confirmed -- convergence achieved.\n\nAppend to worklog:\n`[timestamp] DONE artifact -- steady state (N rounds, M fixes)`\n\nReport: which rounds had fixes, what was fixed, which round first went clean." click STUCK "#" "**Report Unresolved**\nMax rounds exceeded with issues still appearing.\nReport:\n- Which issues persisted across rounds\n- Which models flagged them\n- Why they could not converge\n\nAppend to worklog:\n`[timestamp] STUCK artifact -- Round N, K unresolved, stopping`" click NEXT "#" "**More Artifacts?**\nConvergence processes one artifact at a time.\nIf the queue has more:\n- Pick next artifact\n- Spawn a new teammate for it\n- Loop back to setup\n\nIndividual failures do not stop the batch." click DONE "#" "**Batch Complete**\nAll artifacts in the queue have been processed.\nReview worklog for summary:\n`cat /tmp/council-convergence.md`\n\nReport: N converged, N stuck, total rounds, total fixes." click WLOG "#" "**Worklog**\nAppend-only markdown log at `/tmp/council-convergence.md`\n\nInitialize:\n`echo '# Council Convergence Log' > /tmp/council-convergence.md`\n\nAppend on each event (always `>>`, never `>`):\n`[timestamp] STARTED artifact -- Round 1`\n`[timestamp] FIXED artifact -- 2 issues`\n`[timestamp] CLEAN artifact -- Round 3 (clean count: 1)`\n`[timestamp] DONE artifact -- steady state`\n`[timestamp] STUCK artifact -- max rounds, stopping`" click REMIND "#" "**Heartbeat**\nFor long queues, set `/reminder` every 10 minutes.\n\nOn each check:\n1. Read last N lines of worklog\n2. Check if current artifact has progressed\n3. If no new entries in 10 min, flag as stuck\n4. Report: N complete, N in progress, N pending, any stalls" click TMUX "#" "**Tail Output**\nUse `/tmux` to tail the active teammate's council output log.\nShows live progress of the current debate round.\nUseful for detecting stalls or errors in real time." classDef setup fill:#d1ecf1,stroke:#7ec8d8 classDef debate fill:#dfe6ff,stroke:#5b7bce classDef converge fill:#fff3cd,stroke:#f0c040 classDef fix fill:#ffeaa7,stroke:#e0c040 classDef approved fill:#d4edda,stroke:#5cb85c classDef flagged fill:#f8d7da,stroke:#e06070 classDef monitor fill:#e8daef,stroke:#b07cc6 class GOAL,RUBRIC,TRUTH,ARTIFACT setup class DEBATE,OUTCOME,FIXED,CLEAN debate class RESET,INC,THRESH,MAX converge class STEADY,DONE approved class STUCK flagged class NEXT,WLOG,REMIND,TMUX monitor end style _MAIN_ fill:none,stroke:none,padding:0 _HEADER_ ~~~ _MAIN_