# Review System

The review system is the autobuilder's quality assurance engine. It browses the running application, compares it against the initiative spec and competitors, and creates task PRDs for everything that needs improvement.

## How It Works

Each iteration that includes a review phase:

1. **Mode selection** — Python picks `polish` (90% default) or `feature` (10%) based on `review_polish_weight`
2. **Strategy selection** — Python picks a testing angle from the enabled strategy pool, weighted by historical productivity and recency
3. **Max tasks computation** — Python resolves the effective task limit from the config cascade
4. **Prompt construction** — Python builds the full prompt with mode, strategy focus text, max tasks, browser commands, and credentials
5. **Agent execution** — The AI agent receives the prompt and performs the review

The agent knows nothing about the configuration system. It receives a prompt with specific instructions: "You are reviewing in polish mode using the deep-dive strategy. Maximum tasks: 2." Python decides everything; the agent follows instructions.

## Review Modes

### Polish Mode (default 90%)

The reviewer acts as a bug hunter. It looks for:
- Broken features, console errors, failing tests
- UX friction, confusing navigation, missing affordances
- Visual defects, alignment issues, responsive breakage
- Performance problems, slow loads, unnecessary re-renders

Creates 1–5 tasks per review (configurable via `review_max_tasks_polish`).

### Feature Mode (default 10%)

The reviewer acts as a product visionary. It looks for:
- Missing capabilities vs. competitor
- User-requested features (from backlog)
- Major gaps in the initiative spec
- New user journeys that would add value

Creates 1–3 tasks per review (configurable via `review_max_tasks_feature`).

## Strategy Selection Algorithm

The daemon uses a journal-informed weighted random selection:

1. Load the last 80 journal entries
2. For each strategy in the enabled pool:
   - Compute productivity rate = productive iterations / total iterations (default 0.5 for unseen)
   - Apply a minimum floor of 0.08 (no strategy is fully suppressed)
   - Compute recency bonus = gap since last use / pool size (capped at 3.0)
   - Weight = rate × (1.0 + recency bonus)
3. Normalize weights and sample one strategy

**Fallback:** When fewer than 3 review entries exist in the journal, the daemon falls back to simple round-robin rotation.

**Self-optimization:** Over time, strategies that consistently find issues get selected more often, while strategies that return idle get naturally deprioritized (but never fully suppressed due to the 0.08 floor and recency bonus).

## Built-in Strategies

| Strategy | What It Tests |
|---|---|
| **surface-sweep** | Broad check: navigate every page, check console errors, run test suite |
| **error-handling** | What happens when things break: invalid URLs, empty forms, API errors |
| **edge-cases** | Unusual inputs, boundaries, race conditions, empty states |
| **ux-flows** | Complete user journeys end-to-end (3-5 realistic scenarios) |
| **visual-polish** | Spacing, typography, color, hover states, responsive layout |
| **performance** | Load times, bundle size, re-renders, API waterfalls, caching |
| **deep-dive** | Stress-test the single most complex feature (all buttons, all options) |
| **fresh-eyes** | First-time user perspective: is the app obvious within 10 seconds? |
| **competitor-comparison** | Side-by-side comparison with named competitor on 2-3 sections |

## Browser & Screenshots

During review, the agent uses `agent-browser` CLI to interact with the running application:

```bash
agent-browser open http://localhost:3100
agent-browser wait --load networkidle
agent-browser screenshot .autobuilder/initiatives/0001-my-app/review-screenshots/01-landing.png
agent-browser snapshot -i  # accessibility tree for element inspection
```

- **Screenshots** (`.png`) are visual evidence saved to the initiative's `review-screenshots/` directory
- **Snapshots** are text-based accessibility trees used for element inspection
- Screenshot filenames are sequentially numbered across iterations (Python provides the next prefix)
- The `review-screenshots/` directory is auto-gitignored

## Journal

Every iteration outcome is recorded in `.autobuilder/journal.jsonl`:

```json
{
  "iter": 42,
  "strategy": "deep-dive",
  "mode": "polish",
  "phases": ["review", "plan", "execute"],
  "initiative": "0001-my-app",
  "created": ["0042-fix-chart-tooltip"],
  "executed": ["0038-add-loading-skeleton"],
  "outcome": "productive",
  "rc": 0,
  "ts": 1712700000
}
```

The journal feeds:
- **Strategy selection** — productive strategies get higher weight
- **Memory index** — the agent sees a summary of recent iterations
- **Review history** — compact one-liner in the prompt (e.g., `deep-dive→+2, surface-sweep→idle`)

## Customization

All review behavior is configurable via `.autobuilder/config.yaml`. See [Configuration](configuration.md) for the full reference.

### Common Customizations

**Remove a strategy that doesn't apply to your project:**
```yaml
review_strategies:
  - surface-sweep
  - error-handling
  - edge-cases
  - ux-flows
  - visual-polish
  - performance
  - deep-dive
  - fresh-eyes
  # competitor-comparison  ← not needed for internal tools
```

**Add a domain-specific strategy:**
```yaml
custom_review_strategies:
  - name: data-integrity
    focus: "Verify data accuracy: compare displayed values against API responses, check calculations, validate currency formatting, test with real market data."
    max_tasks: 4
```

**Limit deep-dive reviews to fewer tasks:**
```yaml
strategy_max_tasks:
  deep-dive: 2
```

**Shift to more feature discovery:**
```yaml
review_polish_weight: 0.5
review_max_tasks_feature: 5
```
