# Agent Tuning Pattern

Tuning lets agents adapt to team preferences without modifying the agent definition itself. It follows the supplement pattern from `ticket-delivery`: on first activation, the agent asks a short questionnaire, saves the answers, and reuses them on subsequent runs.

## When to Add Tuning

Add tuning when an agent has 3+ behavioral knobs that different teams would reasonably set differently. Examples:

- A reviewer that some teams want deep and others want surface-level
- An architect that some teams want ADRs from and others want lightweight notes
- A product manager that some teams run with MoSCoW and others with RICE

Do NOT add tuning when:
- The agent's behavior is fixed by design (investigator, cold-reviewer)
- The "knobs" are really just the agent doing its job differently per input
- There are fewer than 3 meaningful settings

## How to Implement

### 1. Add a Tuning section to the agent body

List each knob with its name, options, default, and what it affects:

```markdown
## Tuning

On first activation, this agent checks for a `.reviewer.tune.md` file alongside this agent definition. If missing, it asks the following questions and saves the answers. If present, it loads silently.

| Setting | Options | Default | Effect |
|---|---|---|---|
| `REVIEW_DEPTH` | surface, standard, deep | standard | How many review categories to check |
| `SEVERITY_THRESHOLD` | all, warnings-and-above, critical-only | all | Minimum severity to report |
| `STYLE_FEEDBACK` | yes, no | no | Whether to include style/formatting findings |
```

### 2. Add tune-loading to Process step 1

```markdown
## Process

1. **Load preferences** - Check for `.reviewer.tune.md` alongside this file.
   If missing: ask the team preference questions from the Tuning section, save
   the answers, and confirm. If present: load silently and proceed.
2. [rest of process...]
```

### 3. Reference settings throughout

Use `$VARIABLE_NAME` placeholders in the process and rules:

```markdown
3. **Analyze** - Check each category in the review checklist. If `$REVIEW_DEPTH`
   is `surface`, focus on correctness and security only. If `deep`, include all
   categories plus cross-cutting concerns.
```

## Tune File Format

The tune file follows the ticket-delivery supplement format:

```markdown
# Reviewer Preferences
# Generated by reviewer agent on first activation
# Edit or delete to re-run setup

REVIEW_DEPTH: standard
SEVERITY_THRESHOLD: all
STYLE_FEEDBACK: no
FRAMEWORK_CONTEXT: symfony
```

## Rules

- The tune file is dot-prefixed (`.reviewer.tune.md`) to stay out of agent discovery
- Never force tuning - if the user declines to answer, use defaults
- Keep questions to 3-5 maximum. More than that is a configuration burden.
- Settings should be stable across sessions. Anything that changes per-task is not a tuning knob - it is an input parameter.
