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

# Knowledge Review

> Review and approve knowledge changes before they go live

Your knowledge base is what Delphina relies on to answer questions correctly — so changes to it can be **reviewed before they go live**, the same way code changes go through pull-request review. Knowledge Review gives you a queue of proposed changes, a diff view of exactly what would change, and a policy you control that decides which changes need whose sign-off.

## How it works

When Delphina proposes a knowledge change — from a knowledge update, a validation run, or a chat conversation — the change is packaged as a **batch**: one reviewable unit with a title, the list of affected documents, and a diff of every edit.

* **Every change is proposed as a batch** and gets a permanent record, so there is always an audit trail of what changed and who approved it.
* **If you're a workspace admin** and your own change satisfies the policy, it is approved and merged automatically — you don't wait on yourself.
* **Everyone else's changes wait for approval.** Nothing in the batch takes effect until it is approved and merged.

Pending batches appear in **Context Layer > Inbox** alongside issues. Open a batch to see its diff, why Delphina proposed it, who needs to approve, and a comment thread. Once the required approvals are in, **Approve & merge** applies the batch to the live knowledge base. **Reject** closes it without applying anything.

If the knowledge base changed underneath an open batch in a way that conflicts, the batch is marked **conflicted** — it can't be merged as-is, and the producer (for example, the next knowledge update) will re-propose it against the latest state.

## Deciding who reviews what: the review policy

Every workspace has a review policy — a file named `.delphina/review-policy.yaml` stored inside the knowledge base itself. It answers one question: **for a given change, who must approve it?**

A policy is a list of rules. Each rule matches changes by three things:

* **Which documents** (`paths`) — glob patterns over document paths, like `sales/**` or `**/rule/**`.
* **Where the change came from** (`sources`) — `pipeline` (knowledge updates), `validation-drift` (automatic checks against your warehouse), or `chat-turn` (a person editing through chat).
* **What kind of change** (`change_kinds`) — `addition`, `modification`, or `deletion`.

A matching rule either names the required **approvers** or declares the change safe to **auto-merge**.

### Example

```yaml theme={null}
defaults:
  stale_after_days: 14 # unreviewed batches close after 2 weeks
  escalation_role: "@workspace-admins"
  escalation_after_days: 7

rules:
  # The policy itself is the most protected thing in the workspace — and it
  # comes FIRST, so no broader rule below can match it earlier.
  - paths: [".delphina/**"]
    approvers: ["@workspace-admins"]

  # Business rules are sensitive: your data lead signs off on any
  # pipeline-driven change to them.
  - paths: ["**/rule/**"]
    sources: [pipeline, validation-drift]
    approvers: ["@dana@example.com"]

  # New tables discovered by validation are low-risk: add them automatically.
  - paths: ["**"]
    sources: [validation-drift]
    change_kinds: [addition]
    auto_merge: true
```

By default — with no matching rule — a change requires one approval from a workspace admin. There is no way to make a change skip review just because of *where* it came from; the only paths that land without approval are ones a rule explicitly marks `auto_merge: true`.

**Approvers** come in two forms: workspace role handles (`@workspace-admins`) — any member of the role can approve, and one member's approval counts for the role — or individual people by email (`@dana@example.com`). Custom named groups aren't supported yet; to require sign-off from a specific team, list its members individually.

### Rules are checked top to bottom — order matters

For each changed document, the **first rule that matches wins**. Put your most specific, most protected paths **first**: if a broad rule like `paths: ["**"]` comes before a narrow one, the narrow rule never fires for changes the broad one already matched.

When a batch touches several documents, every affected document's rule applies — the batch needs **all** of the resulting approvals before it can merge. A batch only auto-merges if *every* change in it is auto-mergeable, so a sensitive edit can't slip through by riding along with routine ones.

### What happens with no policy file

Sensible defaults apply until you add one:

* Every change needs one approval from a workspace admin. A workspace admin's own changes satisfy that automatically and merge right away; everyone else's wait for an admin.
* Editing the policy file itself needs a workspace admin's approval too — so the rules of the game can't be changed unilaterally.

Editing the policy is just another knowledge change: it shows up as a batch, gets reviewed under the rules above, and takes effect for batches opened after it merges. Batches already open keep the requirements they were created with.

If the policy file contains an error — a typo in a key, a rule that names no approvers — Delphina **falls back to the default policy** (every change needs an admin's approval) rather than blocking all edits, so an admin can still fix the file. The problem is logged so the team can spot it.

## Keeping the queue healthy

* **Stale batches.** A batch nobody reviews within `stale_after_days` closes automatically. If the change still matters, its producer re-proposes it — your queue reflects what's current, not what's forgotten.
* **Escalation.** If a required approver is unavailable, members of the `escalation_role` can approve in their place after `escalation_after_days`. Escalated approvals are labeled as such in the batch's history.
* **Audit trail.** Every approval, rejection, comment, and escalation is recorded on the batch, and every merged batch is a permanent entry in the knowledge base's version history.