Skip to main content
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.
You can ask Charlie in Slack, GitHub, or Linear to update the policy for you:

​
Start from the installed files

The reference daemon installs three files:
  • 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.

​
Choose where to make the change

Edit the smallest surface that owns the behavior: Charlie owns collecting context, running the applicable lanes, and delivering the review. If one of those is not working, use 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:
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:
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: 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:
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:
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.
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.
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:
Add Do not report only when a realistic false-positive boundary remains after the report condition and evidence requirement:
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

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 for focused guidance.

​
Apply policy changes safely

  1. Make one focused edit on a branch.
  2. From the repository root, run structural validation:
  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 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