# Triage your brain's health findings

**Give this whole file to your agent.** Health findings are not a to-do list to
be cleared as fast as possible — some of them are questions only a human can
answer, and guessing at those destroys content.

> **Your workspace's own values are not filled in here.** Copy this playbook
> from your Blenau dashboard (or `blenau playbooks get <id>`) and it arrives with
> your workspace slug and your connected repos already in it. Ask your agent to
> run `list_repos` first if you are working from this generic copy.

## Step 1 — Read the grouped report first

Call `brain_health()`. The default is `group=True` and you want it: one entry per
casuistry, with the shared procedure stated once and every affected path listed.
Ungrouped, a real workspace returns findings that repeat the same multi-kilobyte
instruction dozens of times — reading the list costs more than doing the work.

Read the two numbers that frame everything else:

- **`score`** is relative to the size of the corpus, not a sum of penalties. It
  always describes the whole workspace, even when you filtered.
- **`summary`** splits findings by severity. Criticals first; "attention" items
  can be legitimate for a long time.

Then narrow with `path=` (a folder or one document), `type=` and `severity=`.
Use `refresh=True` only **after** you fix something — it re-checks GitHub and
costs real API calls.

## Step 2 — Split the list into three piles

**Pile A — repairable, nothing to decide.** Exactly two classes, and the
narrowness is deliberate:

- `sources_unrecorded` — the document already cites its sources in its body and
  only the structured record is missing. Parsing that section *is* the fix.
  Writes one metadata field: never the content, never a commit to your repo.
- `drift_uningested` — a file in GitHub the brain never indexed. Additive, so
  nothing is lost if it turns out to have been a mistake.

Close these with `repair_health(type=…)`. Run it with `dry_run=True` first on a
large batch and **read `truncated`** — a capped run is a partial run, and
reporting it as done is how a class silently stays open.

**Pile B — everything else.** `repair_health` refuses these on purpose, and the
refusal hands you the grouped procedure to follow instead. Do not route around
it. For a structurally damaged document the two plausible remedies are opposite
ones, and picking the wrong one deletes content. Work these one at a time,
following the `prompt` the finding gave you.

Two of them are about a document's EXISTENCE rather than its insides, and both
can end in retiring it — which is a real, supported operation, not something to
work around:

- `empty_document` — the document is still listed, still wearing its title, and
  has no content at all. Either it was emptied by accident (`revert_write` brings
  it back) or it should have been retired (`delete_document`, `dry_run=True`
  first). Find out which before you act; leaving the husk is not an outcome.
- `near_duplicate_document` — two documents say the same thing. Read both. If
  they are the same knowledge, consolidate into one and **retire the other**; a
  consolidation has to end with fewer documents, so never replace the loser with
  a redirect stub. If they are genuinely different, that is Pile C.

**Pile C — not actually defects.** Some findings are correct about the facts and
wrong about the conclusion. These get **dismissed**, not repaired — the dismissal
is recorded per finding, so it survives the next scan and stops burying the ones
that matter.

Be strict about what qualifies. A finding is only Pile C when the document is
genuinely fine as it stands. If it belongs there, say *why* in the dismissal.

Dismiss with `dismiss_health_findings([...])`. It takes finding **ids**, which
the grouped report omits — get them from `brain_health(group=False)` narrowed to
the type you are closing. `restore=True` puts one back.

## Step 3 — Repo-scoped findings are the ones people misread

Three classes are scoped to a **repo**, not to a document: `repo_unreachable`,
`integration_lost` and `raw_missing`. For those, `paths` comes back empty and
`documents` reads **0** even though real documents are affected — the count is
stated in the finding's own `detail` and `prompt`, because the unit the remedy
acts on is the repo.

**Do not read `documents: 0` as "nothing is wrong".** A repo nobody can read
means every document under it stopped being audited, which is exactly how a
renamed repo walks out of the audit taking its documents with it.

`repo_unreachable` has two causes with **opposite** remedies — the repo was
renamed, or access was revoked. The finding tells you which one it is. Check
before acting; applying the other remedy does nothing and looks like it worked.

## Step 4 — Do not invent your way to a clean report

The rule that matters more than the score:

> **Never invent a source so a finding disappears.** A false provenance is worse
> than a missing one — it is a lie the next reader has no way to detect, and the
> whole point of the brain is that an answer can be traced.

If a document's origin is genuinely unknown, it stays unknown. Record what you
do know (the team that owns it, the system it came out of) and report the rest.
The same applies to content: a document that arrived flattened or truncated is
repaired from the original, never reconstructed from what it probably said.

## Step 5 — Close the loop

1. Re-run `brain_health(refresh=True)` scoped to what you touched.
2. Report to the human in three lines: what you repaired, what you dismissed and
   why, and **what you left open because it needs their decision** — with the
   specific question each one is waiting on.
3. If a whole class of finding turned out to be false positives, that is a
   product defect worth reporting, not a list to grind through. A detector that
   is right about the facts and wrong about the conclusion buries the real
   findings underneath it.