consensus-review

What this skill does

# Consensus Review Skill

Multi-agent code review that dispatches specialized reviewers in parallel with adaptive budget allocation and graceful degradation.

## When to Use

- Reviewing pull requests before merge
- Auditing security-sensitive code
- Evaluating architectural decisions
- Code quality assessment with multiple perspectives

## When NOT to Use

- Single-file typo fixes (overkill)
- Simple refactoring with no behavioral changes
- Quick feedback needed (use single reviewer)

## Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                    /consensus-review <scope>                        │
├─────────────────────────────────────────────────────────────────────┤
│  Phase 1: Parallel Initialization                                   │
│  ┌──────────────────────┐  ┌──────────────────────┐                │
│  │   Scope Detection    │  │   File Indexing      │                │
│  │   - Resolve files    │  │   - Index to contextd│                │
│  │   - Detect languages │  │   - Get token counts │                │
│  │   - Select agents    │  │   - Branch metadata  │                │
│  └──────────┬───────────┘  └──────────┬───────────┘                │
│             └──────────────┬──────────┘                            │
│                            ▼                                        │
│  Phase 2: Budget Calculation                                        │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  total_tokens = sum(indexed_file_tokens)                    │   │
│  │  isolation_mode = total_tokens > 16K ? "branch" : "shared"  │   │
│  │  per_agent_budget = calculate_budget(total_tokens, agent)   │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                            ▼                                        │
│  Phase 3: Agent Dispatch (parallel, with budgets)                  │
│  Phase 4: Synthesis (handles partial results)                      │
└─────────────────────────────────────────────────────────────────────┘
```

## Reviewer Agents

| Agent | Focus | Base Budget | Veto |
|-------|-------|-------------|------|
| `security-reviewer` | Injection, auth, secrets, OWASP | 8,192 | Yes |
| `vulnerability-reviewer` | CVEs, deps, supply chain | 8,192 | Yes |
| `go-reviewer` | Effective Go, concurrency | 8,192 | Yes |
| `code-quality-reviewer` | Logic, tests, complexity | 6,144 | Yes |
| `documentation-reviewer` | README, API docs, CHANGELOG | 4,096 | Yes |
| `user-persona-reviewer` | UX, breaking changes, ergonomics | 4,096 | No |

## Adaptive Budget Allocation

See `includes/consensus-review/budget.md` for base budget details.

Budget scales based on BOTH scope size AND complexity tier (from the complexity-assessment skill):

### Base Formula (unchanged)

```
scale = min(4.0, 1.0 + total_tokens / 16384)
per_agent_budget = base_budget[agent] * scale
```

### Complexity Multiplier

After calculating the scope-based budget, apply a complexity multiplier from the complexity-assessment tier:

```
complexity_multiplier = {
  "SIMPLE": 0.75,    # Reduce budget for simple reviews
  "STANDARD": 1.0,   # Standard budget
  "COMPLEX": 1.5     # Increase budget for complex reviews
}

adjusted_budget = per_agent_budget * complexity_multiplier[tier]
```

### Example Calculations with Complexity Tiers

| Scope Size | Tokens | Scale | Tier | Multiplier | Security Budget |
|------------|--------|-------|------|------------|-----------------|
| Small (5 files) | ~4K | 1.25 | SIMPLE | 0.75 | 7,680 |
| Small (5 files) | ~4K | 1.25 | STANDARD | 1.0 | 10,240 |
| Small (5 files) | ~4K | 1.25 | COMPLEX | 1.5 | 15,360 |
| Medium (15 files) | ~16K | 2.0 | SIMPLE | 0.75 | 12,288 |
| Medium (15 files) | ~16K | 2.0 | STANDARD | 1.0 | 16,384 |
| Medium (15 files) | ~16K | 2.0 | COMPLEX | 1.5 | 24,576 |
| Large (50+ files) | ~48K | 4.0 | SIMPLE | 0.75 | 24,576 |
| Large (50+ files) | ~48K | 4.0 | STANDARD | 1.0 | 32,768 |
| Large (50+ files) | ~48K | 4.0 | COMPLEX | 1.5 | 49,152 |

When complexity tier is not available (e.g., standalone review without prior assessment), default to STANDARD (1.0x).

## Isolation Modes

| Total Tokens | Mode | Behavior |
|--------------|------|----------|
| ≤16,384 | **Shared** | Agents run in parent context with budget tracking |
| >16,384 | **Branch** | Each agent gets isolated contextd branch |

### Branch Isolation (Large Scopes)

```
For each agent:
  branch_create(
    description: "{agent} review of {scope}",
    budget: calculated_budget
  )
  → Agent executes in isolated context
  → branch_return(findings_json)
```

## Adaptive Agent Selection

Before dispatching all reviewers, classify the review scope using the complexity tier to determine which agents are needed:

### Triage Matrix

| Complexity | Agents Dispatched |
|------------|-------------------|
| SIMPLE | code-quality-reviewer only |
| STANDARD | code-quality-reviewer + language-specific (e.g., go-reviewer) + security-reviewer |
| COMPLEX | All 6 reviewers |

### Override Rules

Regardless of complexity tier, force-include agents when the diff matches these patterns:

- If diff touches auth/crypto/secrets → always include `security-reviewer`
- If diff includes Go files → always include `go-reviewer`
- If diff modifies public API → always include `user-persona-reviewer`
- If diff changes docs/README → always include `documentation-reviewer`
- If diff adds/updates dependencies → always include `vulnerability-reviewer`

### Triage Workflow

```
1. Determine complexity tier (from complexity-assessment or default STANDARD)
2. Select base agent set from triage matrix
3. Scan diff for override patterns
4. Merge override agents into base set (deduplicate)
5. Dispatch final agent set with calculated budgets
```

This reduces cost and latency for SIMPLE reviews while maintaining full coverage for COMPLEX changes.

## Progressive Summarization

See `includes/consensus-review/progressive.md` for full protocol.

Agents adapt their analysis based on budget consumption:

| Budget Used | Mode | Behavior |
|-------------|------|----------|
| 0-80% | Full Analysis | All severities, detailed evidence |
| 80-95% | High Severity Only | CRITICAL/HIGH, concise evidence |
| 95%+ | Force Return | Stop immediately, `partial: true` |

### Partial Output Schema

```json
{
  "agent": "security-reviewer",
  "partial": true,
  "cutoff_reason": "budget",
  "files_reviewed": 8,
  "files_skipped": 4,
  "skipped_files": ["worker.go", "cache.go", ...],
  "findings": [...],
  "recommendation": "Re-run: /consensus-review worker.go cache.go"
}
```

## Workflow Steps

### 1. Parallel Initialization

Run concurrently:
- **Scope Detection**: Resolve files, detect languages, select agents
- **File Indexing**: Index to contextd with branch metadata, get token counts

### 2. Budget Calculation

```python
total_tokens = sum(file.token_count for file in indexed_files)
scale = min(4.0, 1.0 + total_tokens / 16384)
complexity_multiplier = {"SIMPLE": 0.75, "STANDARD": 1.0, "COMPLEX": 1.5}
tier = complexity_assessment.tier or "STANDARD"  # Default if not available

for agent in selected_agents:
    agent.budget = base_budgets[agent] * scale * complexity_multiplier[tier]
```

### 3. Isolation Decision

```python
if total_tokens > 16384:
    mode = "branch"  # Use contextd branch_create/branch_return
else:
    mode = "shared"  # Run in parent context
```

### 4. Agent Dispatch

```
Task(
  subagent_type: "fs-dev:{agent}",
  prompt: |
    Review {scope}.
    Budget: {calculated_budget} tokens.
    See includes/consensus-review/progressive.md for degradation protocol.
  run_in_background: true
)
```

### 5. Collect & Synthesize

```python
results = []
partial_agents = []

for agent in agents:
    output = TaskOutput(agent.task_id)
    results.append(output)

    if output.partial:
        partial_agents.append({
            "agent": output.agent,
            "files_reviewed": output.files_reviewed,