Triage and clean up your brain's health findings

Hand this whole page to your agent. Copy it from your Blenau dashboard and it arrives with your workspace’s repos already in it; blenau playbooks install brain-health-triage writes it straight into your agent’s instructions folder; or an agent connected over MCP can fetch it itself with get_playbook("brain-health-triage").

Download the raw Markdown

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

Re-run brain_health(refresh=True) scoped to what you touched.
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.
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.