brain-doctor

Brain Doctor

Scan the whole graph for the format mistakes that silently corrupt a Logseq graph — inline code wrapped in {{ }} (broken macros), bare #number/hex tags and un-namespaced [[links]] (phantom empty pages), [[file://]] links, junk/description links, and un-fenced Jira markup residue — plus data-quality checks — malformed properties, broken/duplicate entries, and missing-structure gaps (see the full catalog in skills/_shared/hygiene-rules.md) — then report them and, on confirmation, repair them. This is a maintenance tool: run it on demand, not as part of the save/load cycle.

See skills/_shared/hygiene-rules.md for the full catalog: each rule with its detection pattern, auto-fixable tier, and remediation. The compose-time rules these checks enforce live in skills/_shared/logseq-format.md.

Modes

• Report (default, "lint brain" / "check brain health" / "why are there empty pages"): detect and summarize, change nothing.
• Fix ("fix brain" / "clean up brain" / explicit "yes, fix them" after a report): repair after a backup, with the user's confirmation.

If the trigger is ambiguous, run Report first and offer to fix.

Prerequisites

Resolve the graph path per skills/_shared/path-resolution.md.

Process

1. Scan. For each rule in skills/_shared/hygiene-rules.md with enforced-at: scan (all 14), run its detection across pages/ and journals/. Collect counts and 1–2 example locations per rule. Stay read-only in this phase.

2. Report. Present a compact health summary grouped by the rule's auto-fixable field:

   • Auto-fixable (yes / safe-only): code-in-braces, bare-hash-tag, unnamespaced-link, file-link, malformed-property (safe tiers only).
   • Needs your call (report): description-link, broken-link (with suggested matches), duplicate-entry (the duplicate groups), structural-integrity (missing props / stub sections), jira-markup (unfenced Jira residue — suggests the fence wrap), missing-digest (pages with no digest, largest first), stale-digest (digest older than the page), stale-map (Map claims figures that no longer match the page's measured bytes), oversized-digest (digest over the 800 B cap — report only; never trim on-disk content automatically). Example:

   Brain health: 16 issues across 8 pages
   Auto-fixable (5):  3 {{code}}, 1 bare #tag, 1 malformed property
   Needs your call (7): 2 broken links (1 likely typo → suggests [[Tasks/CRMGM-1982]]),
                        3 duplicate Session Log entries, 2 pages missing last-updated::
   Digests (4):       4 pages with no digest (Fat 109 KB, …) — say "backfill digests"
   

   The headline total counts every bucket — 5 + 7 + 4 = 16. Digests are broken out for readability, never excluded from the count; a total that quietly omits a bucket is the same under-reporting this release exists to eliminate. If the graph is clean, say so and stop — no backup, journey-log just ran brain-doctor (clean).