co8/council-review

Council Review v1

A council reviews; it does not mutate. This skill runs a parallel team of specialized reviewers over a diff, consolidates their findings through a synthesis agent, resolves disagreements in a debate-to-consensus pass, and emits one ranked CODE_REVIEW.md verdict. It stops at the verdict. Execution, repair, and migrations are handed off to swarm-protocol.

This is the shared review primitive. swarm-protocol's review-repair phase invokes it instead of inlining its own dispatch list — one source of truth for what "reviewed" means across every project.

Why a council, not a single reviewer?

• Specialized lenses — each reviewer is a subagent tuned to one failure class. A security reviewer and a type-design reviewer find different bugs; running them as one prompt dilutes both.
• Parallel — all reviewers launch in a single message and run concurrently. Seven lenses cost roughly one lens of wall-clock time.
• Read-only — council agents never write code. No file conflicts, so parallelization is unconditional (no worktree isolation needed).
• Synthesis + consensus — raw reviewer output is noisy and contradictory. The synthesis and debate passes turn N reports into one deduplicated, severity-ranked, conflict-resolved verdict.
• Compliance-aware — a dedicated HIPAA/EU reviewer activates for PHI-touching diffs, with masking discipline so findings never echo PHI or secrets in plaintext.

---

Commands

| Command | Purpose | | ---------------------------------------- | -------------------------------------------------------------- | | /council-review <PR URL> | Review a pull request (pulls diff if source control connected) | | /council-review <branch> | Review a branch diff against its base | | /council-review | Review current uncommitted changes (git diff HEAD) | | /council-review --paste | Review a pasted diff or file |

If no target is provided and there are no uncommitted changes, ask what to review.

---

How It Works

┌──────────────────────────────────────────────────────────────────┐
│                        COUNCIL REVIEW                              │
├──────────────────────────────────────────────────────────────────┤
│  1. SCOPE        Resolve target → unified diff + changed-file map  │
│                                                                    │
│  2. COUNCIL      7 read-only reviewers, ALL in parallel:           │
│     (parallel)   ├─ architect        ├─ silent-failures            │
│                  ├─ correctness      ├─ types + comments           │
│                  ├─ security         ├─ simplification             │
│                  └─ compliance (HIPAA/EU — conditional)            │
│                                                                    │
│  3. SYNTHESIS    1 agent dedupes, normalizes severity, clusters    │
│     (sequential) overlapping findings, attributes each to source   │
│                                                                    │
│  4. DEBATE       Resolve conflicts (reviewer A says fix, B says    │
│     (sequential) leave). Produce consensus + dissent notes.        │
│                                                                    │
│  5. VERDICT      CODE_REVIEW.md — ranked issues + recommendation   │
│                  → Approve / Request Changes / Needs Discussion    │
│                                                                    │
│  ──────────────  council stops here. mutation is swarm's job. ──── │
└──────────────────────────────────────────────────────────────────┘

---

Step 1: Scope

Resolve the review target into a unified diff and a changed-file map.

• PR URL → if source control is connected, pull the diff and CI status. Otherwise ask for the diff.
• Branch → git diff $(git merge-base HEAD <base>)..HEAD (default base: main).
• No args → git diff HEAD (uncommitted) and staged changes.
• --paste → use the provided diff/file directly.

Build a changed-file map and classify the change surface. The classification drives conditional reviewer activation in Step 2:

| Signal in diff | Activates | |---|---| | Paths touching PHI, audit trails, patient data, auth on health data | Compliance reviewer (HIPAA/EU) | | New/changed migrations, schema, RLS policies | Security reviewer escalated focus + flag for swarm handoff | | New public types, exported interfaces | Type design reviewer escalated focus | | Net-new modules, cross-cutting refactors | Architect escalated focus |

Write the diff + map to CODE_REVIEW.md header before dispatching, so the council shares one canonical view of the change.

---

Step 2: The Council (Parallel — launch ALL in a single message)

Dispatch all active reviewers as read-only subagents in one message with multiple Agent tool calls. Council agents MUST NOT write to the working tree — they return findings only.

| # | Agent | Subagent Type | Lens | |---|-------|--------------|------| | C.1 | Architect | feature-dev:code-architect | Boundaries, coupling, abstraction fit, does this belong here, will it scale | | C.2 | Correctness | feature-dev:code-reviewer | Logic errors, edge cases (null/empty/overflow), race conditions, off-by-one | | C.3 | Security | feature-dev:code-reviewer (security prompt) | OWASP top 10, injection, authz flaws, secrets in code, SSRF, path traversal | | C.4 | Silent Failures | pr-review-toolkit:silent-failure-hunter | Swallowed errors, bad fallbacks, inadequate error propagation | | C.5 | Types + Comments | pr-review-toolkit:type-design-analyzer | Type encapsulation, invariant expression; stale/misleading comments | | C.6 | Simplification | pr-review-toolkit:code-simplifier | Unnecessary complexity, redundancy, clarity, dead code | | C.7 | Compliance | feature-dev:code-reviewer (compliance prompt) | Conditional. HIPAA/EU (GDPR) exposure, audit-trail integrity, consent, PHI handling. See masking rules below. |

C.5 merges the napkin's separate type and comment lenses — type-design-analyzer covers both encapsulation and the comment-accuracy check, and one agent over a shared diff avoids a redundant pass. If a diff is comment-heavy (docs refactor), split C.5 into a dedicated pr-review-toolkit:comment-analyzer agent.

Each reviewer returns a structured finding list: {severity, file, line, lens, issue, suggested_fix, confidence}. Severity is one of Critical / High / Medium / Low / Nit. Reviewers do not rank across lenses — that is synthesis's job.

Compliance masking rule (C.7)

When the compliance reviewer cites a finding, it MUST mask any PHI, secrets, tokens, or identifiable patient data in its output — reference the location and the class of data, never the value. A finding reads auth/session.ts:42 — PHI (patient DOB) logged in plaintext, never the DOB itself. This mirrors the scoda secrets-broker fail-closed posture: a review artifact is a shared document and must never become a new leak surface.

---

Step 3: Synthesis (Sequential — after all reviewers return)

One synthesis agent (general-purpose) consolidates the raw council output:

1. Deduplicate — multiple reviewers often flag the same line. Collapse into one finding, union the lenses that raised it (a bug flagged by both correctness and security is higher-signal).
2. Normalize severity — apply one consistent severity scale across all lenses. A simplification "Critical" is not a security "Critical"; re-rank against a shared rubric (see references/severity-rubric.md).
3. Cluster — group related findings (e.g. five symptoms of one missing validation) under a root cause.
4. Attribute — every consolidated finding keeps its source lens(es) for traceability.

Output: a single ranked findings table written to CODE_REVIEW.md.

---

Step 4: Debate → Consensus (Sequential)

Reviewers disagree. The architect may want a refactor the simplifier calls over-engineering; security may demand a check correctness considers unreachable. Resolve before issuing a verdict.

Protocol:

1. Identify findings with conflicting recommendations or where one reviewer's fix would violate another's lens.
2. For each conflict, the synthesis agent argues both positions explicitly (steelman each), then picks a resolution with a one-sentence rationale.
3. Unresolved or genuinely judgment-call conflicts are recorded as dissent notes — surfaced to the human, not silently dropped.

This is the genuinely novel layer neither code-review nor swarm-protocol had: the output is reconciled, not a pile of contradictory opinions. It also enforces your house rule — every issue ends with options + a recommendation + why.

---

Step 5: Verdict

Emit CODE_REVIEW.md and a terminal summary. Structure:

## Council Review: <target>

### TL;DR
<3 lines: overall quality, blocker count, the one thing that matters most>

### Verdict
Approve | Request Changes | Needs Discussion

### Findings (ranked)
| # | Severity | File:Line | Lens(es) | Issue | Recommendation |
|---|----------|-----------|----------|-------|----------------|

### Conflicts Resolved
| Conflict | Position A | Position B | Resolution | Why |

### Dissent (unresolved — human call)
- <finding> — <competing views>

### What Looks Good
- <positive observations — real ones, not filler>

### Handoff
- Repairs for swarm-protocol: <count by severity>
- Migrations / schema changes flagged for swarm Supabase workflow: <list or none>

The verdict is the terminal artifact. Council does not fix anything. If repairs are wanted, hand CODE_REVIEW.md to swarm-protocol --review-only's repair conductor (see Handoff below).

---

Options

| Flag | Purpose | | ------------------- | ----------------------------------------------------------------------- | | --paste | Review a pasted diff/file instead of resolving a git/PR target | | --base=<ref> | Set the merge-base for branch diffs (default: main) | | --lenses=<list> | Run only named lenses, e.g. --lenses=security,correctness | | --no-compliance | Force-skip the compliance reviewer even if PHI signals are detected | | --compliance | Force-enable the compliance reviewer regardless of detected signals | | --quick | Skip debate pass; emit synthesized findings without conflict resolution | | --max-agents=N | Cap concurrent reviewers (default: all active lenses) | | --json | Emit findings as JSON alongside CODE_REVIEW.md (for ScopeTUI / CI) |

---

Handoff to swarm-protocol

Council is the review half of a two-skill contract:

• council-review owns review → produces CODE_REVIEW.md (read-only, no mutation).
• swarm-protocol owns repair + verify + Supabase deployment → consumes CODE_REVIEW.md.

swarm-protocol's review-repair phase should invoke this skill for the review step, then run its existing repair conductor over the verdict. The two skills share the CODE_REVIEW.md schema as their contract surface — see references/code-review-schema.md.

One-line change in swarm-protocol (SKILL.md, "Phase Review & Repair"): replace the inline 5-agent dispatch table with → invoke council-review skill, then run Repair over its CODE_REVIEW.md. Council adds the architect + compliance lenses swarm lacked, so swarm inherits them for free.

---

When NOT to use council-review

• Trivial diffs (typo, version bump, copy change) — a full council is overkill; eyeball it.
• Mid-implementation sanity checks — use a single feature-dev:code-reviewer agent; the council is a merge gate, not a linter.
• When you want fixes, not findings — council only reviews. Use /swarm-protocol --review-only for review-then-repair in one pass.

---

Best Practices

Resolve scope precisely → activate compliance for any PHI surface → launch the whole council in one message → never let council agents write code → synthesize before verdict → resolve conflicts explicitly with rationale → mask PHI/secrets in every finding → hand repairs to swarm, don't fix in place → keep the TL;DR to three lines.

Reference Files

| File | Load When | | ------------------------------------- | ------------------------------------------ | | references/reviewer-prompts.md | Always (per-lens dispatch prompts) | | references/severity-rubric.md | Synthesis step (cross-lens severity scale) | | references/code-review-schema.md | Always (CODE_REVIEW.md contract w/ swarm) | | references/compliance-masking.md | PHI / HIPAA / EU signals present |