Second Brain Audit

Second Brain Audit

Notes rot in a specific way. Nothing is corrupted and nothing goes missing: a fact simply stops being true, the note keeps saying it, and nothing raises a hand.

The cause is almost always the same. The write path can only append. New information arrives and becomes a new line under the old line, which is correct for some facts and ruinous for others.

The one idea

Every stored fact is one of two kinds.

A price, a status, an owner, a deadline: state. A payment, a signature, a decision, a lesson learned: event.

The update rules are opposites. Replacing an event destroys history. Appending a state creates two answers to one question with nothing marking which is current, and the stale copy usually sits higher in the file, so it gets read first.

Structure carries this rule, not an instruction. Asking a model, or a person, to remember to update the old entry fails quietly and constantly. Give the page two sections and the rule follows from where a fact lands.

Phase 1: establish the shape

Do not assume a wiki, a vault, or pages. Most people have none of those. Look at what actually exists before anything else, because it changes both what the audit can see and what the fix should be.

The notes folder this run was invoked with is $notes, and it is optional (/second-brain-audit ~/notes). Use it when it is a real path. When nothing was passed, so the line above still reads \$notes, use the working directory and confirm it with the user. When it is a path that does not exist, say so and stop rather than auditing the wrong folder.

Then establish two things:

1. Where the notes live. A folder of markdown, for the scan.
2. What the agent reads on every session. CLAUDE.md, a MEMORY.md, a system prompt file, whatever loads automatically. This matters more than anything else: a stale fact in an archive is harmless, the same fact in the always-loaded file is the bug. If the user does not know, say so and run without it.

Daily-notes-only is the case most worth naming out loud. Dated notes are an event log, and events are supposed to accumulate; nothing about them is broken. What is missing is any place that says what is true now. Telling someone to restructure their journal would be actively wrong.

Phase 2: audit the always-loaded surface

This is the part that works on every second brain, in any tool, in any domain, with or without the script. Run it always, even when the scan found plenty.

Whatever the agent reads on every session is small: that is what makes it always loadable. So it can be read in full and checked claim by claim.

1. Read that surface completely. The always-loaded file, or the top of the one big file, or the pinned page. All of it. Then check it actually arrives in full: hooks and context budgets truncate, usually from the bottom, and a file that is "always loaded" on disk can reach the agent as its oldest third. Audit what arrives, and treat the cut itself as a finding.
2. Extract every state-shaped claim. Anything phrased as a current fact: a status, an owner, a rate, a version, a deadline, a "currently", a "we use", a "lives at". Ignore anything phrased as an event, since events stay true.
3. For each claim, go and find the freshest evidence anywhere in the notes. Grep the subject. Read the newest file that mentions it.
4. Sort each claim into three piles:
   • Confirmed. The detail agrees.
   • Contradicted. Something newer disagrees. This is rot, and it is the headline.
   • Unsupported. Nothing anywhere backs it up. Often the claim was true once and the evidence was never written, which is worth saying out loud.

Ten to thirty claims is normal, and it is a few minutes of reading. A research vault with no money in it, a personal wiki, a Notion workspace: all auditable this way, and none of them by the script.

Report the contradicted pile first, then the unsupported pile. Both are findings.

Phase 3: run the scan, if the notes suit it

An accelerator, not the audit. It applies to markdown folders where facts carry monetary values, and it finds cross-file disagreements far faster than reading can. Skip it otherwise; phase 2 already did the work.

python <skill>/scripts/audit.py <notes-dir> \
    --always-loaded MEMORY.md --always-loaded CLAUDE.md \
    --subject rate --subject <one word per subject that matters>

Pass --subject for every subject you care about, one word each (rate, not "Hourly rate"), and --json for structured output. On a small folder the script attributes values by page name and bold key only, so without --subject a real cross-file contradiction can come back as a clean zero with no warning. The script counts; phase 2 is the audit. It only reads; it never writes.

A zero is not a clean bill of health. Values are the only thing it can compare without guessing, so notes with no money in them are largely invisible to it, and so is a status that changed while the amount did not ("$32,300 due" versus "$32,300 on hold" is the same number). Its "0 touch a file your agent loads" line counts money only; the always-loaded file is audited in phase 2, never by this count. It prints a COVERAGE WARNING when it knows it was blind. Read that warning out rather than reporting "no problems found".

Why a script at all: the count has to be the same twice. A model asked to tally 600 bullets returns a confident number and a different one tomorrow, which is the class of failure this skill exists to fix. The script counts. The agent judges.

Phase 4: read what neither can see

Open a few flagged pages and look for what no regex will catch:

• Lifecycle conflicts. A page saying "launching next week" while a log entry from three months ago records the project being cancelled. No number disagrees, so nothing is flagged, and it is completely wrong.
• Facts never written down at all. The most common cause of a wrong answer is not bad organization; it is that the true value only ever existed in a conversation or a daily note. Reorganizing cannot reach it. Say so plainly rather than implying the restructure will help.
• Pages that must not be touched. Checklists, reference lists, packing lists. They are lists on purpose. Converting one destroys what makes it useful, and every structural check still passes.
• Two true lines, one impossible schedule. Each Current State line is checked against its own subject; nothing checks two lines against each other. Two deliverables "live 9/23" on two keys is either a real conflict or a shared host video, and the lines should say which. Grep the block for repeated dates.
• A fresh date on a value nobody checked. A rewrite that re-dates lines it merely moved, or a "rows verified today" note over a table seeded months ago, gives stale values the one thing that would have exposed them. Check what git blame says about a freshly dated line before trusting the date; a date is a claim that the value was verified, not a stamp that the line was touched.
• Key sprawl. One subject spread across many Current State keys ("Brief 10050 draft", "Brief 10050 review pass", "Brief 10050 record day"). Every key is unique, so the duplicate check passes, and the freshest of them can still be stale. The reverse of the duplicate-key bug, and the same fix: one key per thing that has one status. Report it; collapsing is the owner's call.

Phase 5: report

Lead with the single most damaging finding, not a summary of the tool's output:

Three different answers for what Acme pays, and the oldest one is in the file the agent reads every session.

Where an agent already runs over these notes, demonstrate it. Ask the question the notes should answer and read the reply out. Watching an assistant confidently return a number that stopped being true in March lands harder than any report. Point out the common case where it is diligent and still wrong: it checks a page, warns that another file looks stale, and still misses the true value because that value was never promoted anywhere durable.

On a small folder a capable agent will read everything and find the truth. Confine the demonstration to what the agent is actually handed every session (paste the always-loaded file alone, or run with read tools off) and ask again. The gap between the two answers is the finding.