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

# PR Comments (the Auditor)

> One signal-anchored comment: the Auditor’s finding plus the team’s recorded context.

Driftless posts exactly one kind of PR comment, the **Auditor's**, and it only posts when it has a finding. When a pull request touches documented areas, the Auditor reviews the change against the team's recorded context. If the change may contradict something the team wrote down, it posts **one comment**: the finding, with the affected topics' gotchas, decisions, and invariants riding along. The reviewer sees the signal *and* the memory behind it, together.

A clean PR gets **no comment at all**. There is no "here's everything we know" comment on every PR that touches an anchored file. That kind fired on a mere file-match, read as spam, and trained reviewers to ignore the bot.

## How it works

When a PR is opened or updated:

1. Driftless fetches the changed files and matches them against every topic's anchors (globs).
2. Every PR↔topic match is **recorded** (it powers the dashboard's PR activity), comment or not.
3. If the workspace has the Auditor configured (a model key in **Settings → Agents**), the Auditor is queued: it reads the real diff against the matched topics' recorded claims.
4. **Only if it finds something** does it post a single sticky comment, updated in place on later commits, never re-posted.

## What the comment delivers

```text theme={"theme":"github-light"}
## 🔎 Driftless Auditor

This change may affect 2 things the team recorded. Queued for review,
these are Suggested edits; an owner/admin merges them.

- `billing-flow` (Suggested edit): refund window changed 7d→30d
- `auth-boundaries` (needs a human): new route bypasses the workspace guard

### What the team already knows

#### `billing-flow`: Stripe billing and refund handling
**Gotchas**
- Stripe delivers webhooks at-least-once, so consumers must be idempotent
**Invariants**
- Webhook handlers must read event.id and short-circuit on duplicate
```

Stale topics are flagged inside the comment ("trust the code over the note, then update it"). Topics with nothing recorded yet contribute the finding line only.

## Signal-only, by design

* **No finding → no comment.** Silence is the default, and it's information too.
* **No model key → no comment.** The Auditor is BYOM; without a key the PR is still observed and recorded, just not commented.
* **It informs; it never blocks.** Findings land as Suggested edits in the Review Queue, and an owner/admin merges them. No coverage score, no homework.
* **Gap-finding lives in the coverage map**, not in PR comments: `driftless_context_coverage` over the MCP, or the dashboard.

If your change altered how an area works, update the topic so the note stays true:

```bash theme={"theme":"github-light"}
driftless context update auth-boundaries --gotcha "..." --decision "..."
# or open a Suggested edit if it's already Knowledge:
driftless context pr auth-boundaries --open --summary "..." --content @new.md
```

<Note>
  The comment respects governance: findings are Suggested edits, never auto-applied, and the context it surfaces distinguishes Knowledge from Notes. See [Governance](/concepts/governance) and [Agents](/agents/agentic-layer).
</Note>