# Setup guide — Flaky Test Triage Agent

## 1. Install and connect CI

Install the agent and connect it to your CI and test reporting.

```
pipx install flaky-triage-agent
flaky-triage-agent connect --ci github-actions --reports junit
flaky-triage-agent doctor   # verifies isolated re-run capability
```

## 2. Configure confirmation and caps

How many isolated re-runs, and how much evidence is needed to call flaky. Enforced outside the model.

```
cp .env.example .env
ANTHROPIC_API_KEY=sk-ant-...
MAX_RERUNS=5
FLAKY_NEEDS: { isolated_pass: true, history_intermittent: true }
MODE=advise   # advise (recommend) | act (auto-quarantine proven flakes)
```

## 3. Mark critical-path suites

These never auto-quarantine, even if they look flaky.

```
# .flaky.yml
critical_paths: ["tests/payments/**", "tests/auth/**", "tests/data_integrity/**"]
quarantine: skip_with_issue   # never delete
assign_owner_from: CODEOWNERS
```

## 4. Dry-run on recent failures

Replay recent red builds to check verdicts before enabling auto-quarantine.

```
flaky-triage-agent backtest --range 14d --explain
# reports flaky/real accuracy and any regressions it would have masked (must be 0)
```

## 5. Wire into the pipeline

Trigger on test failures. Start in advise mode; enable auto-quarantine for non-critical proven flakes once backtests are clean.

```
# CI failure hook -> POST https://your-host/flaky/triage (HMAC)
# promote MODE=act after a clean backtest with zero masked regressions
```
