> ## Documentation Index
> Fetch the complete documentation index at: https://docs.charlielabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure

> Change when Charlie reviews, what he looks for, and how he publishes feedback.

The `pr-review` daemon is your repository's review policy. Change it through normal pull requests, and keep each edit focused on one behavior you want to observe.

<Tip>
  You can ask Charlie in Slack, GitHub, or Linear to update the policy for you:

  ```text theme={null}
  Update the `pr-review` daemon so [describe the behavior you want]. Change only the smallest relevant policy section and open a pull request.
  ```
</Tip>

## Start from the installed files

The reference daemon installs three files:

```text theme={null}
.agents/daemons/pr-review/
├── DAEMON.md
└── references/
    └── lanes/
        ├── correctness.md
        └── repository-guidance.md
```

* `DAEMON.md` defines when reviews run and the policy shared by every review.
* `correctness.md` looks for evidence-backed correctness problems.
* `repository-guidance.md` checks applicable repository instructions and durable local conventions.

Only direct Markdown files matching `references/lanes/*.md` are review lanes. Files in nested directories are not selected as lanes. Other Markdown under `references/` can provide supporting guidance without becoming a separate review perspective.

Start from the [`pr-review` example in `charlie-labs/daemons`](https://github.com/charlie-labs/daemons/tree/master/daemons/pr-review).

## Choose where to make the change

Edit the smallest surface that owns the behavior:

| What you want to change                                | Where to change it                                |
| ------------------------------------------------------ | ------------------------------------------------- |
| When reviews run                                       | `watch` in `DAEMON.md` frontmatter                |
| A rule that applies to every review                    | The relevant policy section in `DAEMON.md`        |
| One perspective's applicability, concerns, or evidence | Its file in `references/lanes/`                   |
| A new review perspective                               | A new direct Markdown file in `references/lanes/` |
| A development rule for authors and reviewers           | Repository instructions or documentation          |
| Required human approval or merge enforcement           | GitHub branch protection or checks                |

Charlie owns collecting context, running the applicable lanes, and delivering the review. If one of those is not working, use [Troubleshooting](/pr-reviews/troubleshooting) instead of adding execution instructions to your policy.

## Change when reviews run

The reference `watch` policy starts a review when:

* A non-draft pull request is opened.
* A draft pull request is marked ready for review.
* `CharlieHelps` is requested as a reviewer.
* A pull request comment requests a review from `CharlieHelps`.

The reference policy does not review every new commit by default. Review lanes also do not start reviews: `watch` controls cadence, while each lane's applicability guidance controls whether that perspective participates after a review starts.

### Require an explicit request

To disable automatic reviews:

1. Remove the conditions for opening a non-draft pull request and marking a draft ready.
2. Keep the conditions for requesting `CharlieHelps` as a reviewer and requesting a review in a pull request comment.

Opening or readying a pull request will no longer start a review. Someone must request one explicitly.

### Review every new commit

Add this condition to `watch`:

```yaml theme={null}
- A new commit is pushed to an open non-draft pull request.
```

Keep the open and ready conditions if you also want an initial automatic review. Reviewing every commit increases review volume and cost, so use focused lanes and a clear rereview policy.

### Leave the daemon's role intact

`watch` is the normal cadence control. The reference `purpose` and `routines` define the daemon's role; changing them changes or forks that role.

Do not add lane orchestration, package commands, retry behavior, idempotency rules, or publication instructions. Charlie owns those mechanics.

Keep this standalone line in the body of `DAEMON.md` exactly once:

```text theme={null}
PR review protocol: pr-review/v1
```

The protocol connects your policy to compatible review mechanics. It is not a package version for your repository to install or pin.

## Configure review-wide policy

Use `DAEMON.md` for decisions that must govern the whole review. The reference policy organizes those decisions into nine sections:

| Section                      | What it controls                                           |
| ---------------------------- | ---------------------------------------------------------- |
| `Never leave feedback about` | Categories excluded from every review lane                 |
| `Review outcomes`            | Allowed GitHub review outcomes and clean-review behavior   |
| `Review depth`               | How much context Charlie should inspect                    |
| `Artifact treatment`         | How different file and artifact types should be reviewed   |
| `Findings and verification`  | The evidence bar, verification rules, and finding format   |
| `Incomplete reviews`         | What happens when part of a review cannot be completed     |
| `Review requests`            | How focused requests affect the current review             |
| `Final review`               | Finding selection, ordering, placement, and tone           |
| `Rereviews`                  | How follow-up reviews treat prior feedback and new changes |

The headings are Markdown policy, not a fixed schema. Keep them when they make the policy easy to inspect, and change the content only when you want the corresponding behavior to change.

### Exclusions and evidence

Use `Never leave feedback about` for a small number of genuine cross-lane vetoes. The reference policy excludes personal preferences without a concrete risk, pre-existing problems the pull request did not worsen, expected generated-artifact changes without material risk, and problems already explained by deterministic checks or another review.

Keep global exclusions narrow. A broad rule can hide a valid finding from every perspective. Put a concern-specific false-positive boundary in the relevant lane instead.

`Findings and verification` defines what a candidate must establish before Charlie publishes it. The reference policy requires:

* A concrete issue.
* A plausible trigger or supporting evidence.
* A material consequence.
* A clear required action.

Charlie can run targeted checks when they resolve a material uncertainty. A failed, unavailable, or inconclusive tool is not evidence by itself.

The reference finding header includes severity and the originating lane:

```md theme={null}
**1. Short descriptive title** | `🔴 blocking` | `§ correctness`
```

Use `🟠 non-blocking` for findings that do not need to be addressed before merge. Keep the exact lane name so readers can trace the finding to its policy. The reference policy does not use numeric severity or confidence scores.

### Review depth and artifact treatment

`Review depth` controls how much surrounding context Charlie should inspect. The reference policy reviews the diff plus enough callers, dependencies, tests, contracts, and repository guidance to establish the effect of the change.

Large pull requests do not lower the evidence bar or impose a finding cap. If size or another constraint materially narrows coverage, use the incomplete-review policy instead of lowering the standard.

`Artifact treatment` lets you set different expectations for different kinds of files. The reference policy:

* Fully reviews runtime code, configuration, schemas, migrations, infrastructure, CI, and dependency manifests.
* Reviews tests and fixtures for concrete verification gaps or contract conflicts, not speculative production findings.
* Reviews documentation, examples, renames, moves, deletions, and binaries when an applicable rule or concrete material risk exists.
* Ignores expected generated, vendored, snapshot, lock, and build-artifact changes unless the artifact itself creates a concrete material risk.

Adjust these rules when your repository has a different source-of-truth model or risk profile.

### Review outcomes and incomplete reviews

The reference policy permits `COMMENT` only. When useful findings qualify, Charlie publishes them in one `COMMENT` review. When every applicable lane completes with no useful finding and no coverage limitation, Charlie leaves exactly one `+1` reaction on the pull request body. He does not publish an empty review, summary, praise, or `LGTM`.

To keep that behavior explicit:

```md theme={null}
## Review outcomes

- When publishing a formal PR review, use `COMMENT`.
- When a finding should be addressed before merge, say so directly in the finding.
- For a clean review, ensure Charlie has exactly one `+1` reaction on the pull request body.
- Do not publish a formal review, comment, summary, praise, or `LGTM` for a clean review.
```

You can also authorize `APPROVE` or `REQUEST_CHANGES`. Define an observable threshold for each outcome and decide whether a clean review should produce an approval or retain the reference `+1` behavior.

<Warning>
  `APPROVE` and `REQUEST_CHANGES` participate in GitHub's review system. GitHub permissions and branch-protection rules determine their merge effect. Repository policy does not replace deterministic merge controls or a required human approval.
</Warning>

`Incomplete reviews` controls what happens when Charlie cannot finish every applicable part of a review. The reference policy still publishes independently supported findings and adds at most one concise limitation note. It publishes a limitation-only comment only when silence could reasonably look like a completed clean review.

### Final review presentation

Use `Final review` to control:

* Which eligible findings appear and in what order.
* Inline placement for precise changed-line concerns versus review-body placement for cross-file concerns.
* Tone and verbosity.
* When a suggested fix is useful.
* How overlapping findings should be consolidated.

The reference policy publishes every distinct finding that meets the evidence bar. It combines symptoms of one underlying problem, keeps independent risks separate, puts blocking findings first, and omits generic summaries and praise.

Avoid a hard finding cap unless your team deliberately accepts the risk of hiding otherwise useful feedback. Narrow lanes and strengthen applicability when you need less noise.

### Focused review requests

`Review requests` defines how Charlie treats a comment that asks him to focus on something specific. The reference policy lets the request focus attention for that review, but it cannot suppress applicable lanes or override trusted repository policy.

### Rereviews

`Rereviews` defines how follow-up reviews treat the current pull request and earlier feedback. The reference policy:

* Considers the full current pull request while focusing on changes since the previous review and behavior those changes affect.
* Does not repeat findings that were resolved, dismissed with supporting evidence, or explicitly accepted by an authorized maintainer unless new evidence materially changes the risk.
* Avoids duplicating human or automated feedback unless Charlie adds a distinct consequence, requirement, or useful diagnosis.
* Corrects or retracts prior Charlie feedback when later evidence shows it was wrong.

Charlie-owned mechanics prevent duplicate GitHub mutations. Your policy decides whether the underlying feedback is still useful and should appear again.

## Configure review lanes

Each direct Markdown file in `references/lanes/` defines one independently understandable review perspective. Charlie inventories those lanes, selects the applicable ones using their authored applicability guidance, and applies the root policy to the resulting candidates.

The installed correctness and repository-guidance lanes are starting choices. You can edit, add, remove, or replace them.

### Write one perspective per lane

A lane should answer:

1. When does this perspective apply?
2. Which concrete concerns should it investigate?
3. When is each concern reportable?
4. What evidence must support a finding?

Use headings to make those decisions easy to review without treating them as required schema:

```md theme={null}
# [Perspective name]

## Applies when

- Use this lane when [the change makes this perspective useful].
- Skip it when [the perspective cannot add useful review judgment].

## Concerns

- **[Concrete concern]**
  - **Report when:** [Observable condition that makes this a real problem.]
  - **Evidence:** [Code, test, contract, or repository evidence needed to support it.]
```

Add `Do not report` only when a realistic false-positive boundary remains after the report condition and evidence requirement:

```md theme={null}
- **Incorrect behavior on a reachable path**
  - **Report when:** Changed code produces an incorrect result for a concrete input, state, configuration, or dependency result.
  - **Evidence:** Show how the path is reached, what should happen, what happens instead, and the consequence.
  - **Do not report:** Hypothetical edge cases without a plausible execution path or observable consequence.
```

A focused lane often contains three to seven coherent concerns. This is an authoring heuristic, not a validation rule. Split a lane when its concerns need materially different applicability or evidence. Combine lanes when they repeatedly investigate the same behavior.

### Prefer conditions and evidence

| Avoid                               | Prefer                                                                                                                                        |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `Review failure handling.`          | Report a failure-handling issue only when a reachable path can return the wrong result, conceal a required failure, or leave work incomplete. |
| `Report anything that might break.` | Require a concrete reachable path, expected behavior, actual behavior, and material consequence.                                              |
| `Never report edge cases.`          | Do not report hypothetical edge cases without a plausible execution path or observable consequence.                                           |

Use narrow suppressions for recurring false positives. A universal veto usually hides legitimate findings along with the noise.

### Decide which repository sources are authoritative

The reference repository-guidance lane uses these defaults:

* Policy from the default branch governs the review.
* A more specific path instruction can strengthen a root rule, but does not silently weaken it.
* Code, tests, schemas, and neighboring files are evidence. They are not automatically policy.
* The pull request description and conversation provide context. They are not durable repository policy.

Change these rules if your repository has a different documented authority model. Keep the precedence explicit so Charlie does not have to infer it from conflicting examples.

### Narrow, add, or remove a lane

When a lane is noisy, make the smallest effective edit:

* Narrow its applicability when the whole perspective runs unnecessarily.
* Tighten `Report when` when a concern fires without the condition that makes it harmful.
* Strengthen `Evidence` when findings are plausible but unsupported.
* Add a narrow `Do not report` example for one recurring safe case.
* Remove a concern or lane when it no longer earns its review cost.

Add a perspective by creating one direct Markdown file in `references/lanes/`. Remove it by deleting that file through a normal pull request. There is no root lane registry to update, and each remaining lane should stay understandable on its own.

## Control cost and scope

PR review cost is mainly shaped by cadence, lane count, lane applicability, and review depth. Large pull requests require more investigation, and a review still consumes work when no visible finding qualifies.

Start by reducing unnecessary reviews and making applicability more precise. Remove or narrow lanes whose accepted value no longer justifies their cost, latency, or overlap with other perspectives. Change one dimension at a time so you can tell what improved.

See [Control PR review costs](/pr-reviews/cost-control) for focused guidance.

## Apply policy changes safely

1. Make one focused edit on a branch.

2. From the repository root, run structural validation:

   ```bash theme={null}
   bunx @charlie-labs/daemons validate --all
   ```

3. Inspect the diff and explain the intended behavior change in the pull request.

4. Merge the change to the default branch.

5. Allow a few minutes for Charlie to load the updated policy.

6. Exercise the change on a separate representative pull request.

7. Compare the GitHub result and [Dashboard Activity](https://dash.charlielabs.ai/) with the policy.

The CLI validates daemon file structure and frontmatter. It does not validate review meaning, lane quality, the PR review protocol, routing, repository access, or live output.

PR review policy only takes effect from the default branch. To prevent a change from defining the rules used to judge itself, Charlie does not run a daemon-powered review on a pull request that changes `DAEMON.md` or reference Markdown for the `pr-review` daemon. Merge the policy change, wait for Charlie to load it, and test it on another pull request.

Do not broaden the policy merely to make Charlie publish something. A fully completed clean review produces the configured clean result rather than a finding.

## What Charlie handles

Your policy defines review judgment. Charlie gathers the current pull request context, inventories the lanes, selects the applicable lanes from their authored guidance, applies the root policy to the resulting candidates, and delivers the review.

## Next steps

* [Control PR review costs](/pr-reviews/cost-control) to reduce review frequency or scope.
* [Troubleshooting](/pr-reviews/troubleshooting) when a review does not run or its result is unexpected.
* [PR review overview](/pr-reviews) for the product model and setup path.
* [`DAEMON.md` reference](/daemons/daemon-md-reference) for the generic daemon file contract.