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.
| Meaning | Correct update |
|---|
| State | one current value, and it changes | replace it |
| Event | a timestamped thing that happened | append it |
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.
| Shape | Looks like | Where state should live |
|---|
| Page per subject | , | two sections on each page |
| One big file | a single or | a block at the top |
| Daily notes only | , and nothing else | nothing to convert. A state layer is missing entirely |
| Not markdown | Notion, Apple Notes, a chat assistant's memory | the idea still applies; the tooling does not |
Then establish two things:
- Where the notes live. A folder of markdown, for the scan.
- What the agent reads on every session. , a , 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.
- Read that surface completely. The always-loaded file, or the top of the one
big file, or the pinned page. All of it.
- 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.
- For each claim, go and find the freshest evidence anywhere in the notes.
Grep the subject. Read the newest file that mentions it.
- 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.
bash
python <skill>/scripts/audit.py <notes-dir> \
--always-loaded MEMORY.md --always-loaded CLAUDE.md
Pass
to track named subjects by name, and
for
structured output. The script 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. 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.
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.
Phase 6: fix one place
Never bulk-convert, and never convert a page the user did not agree to. Fix the
single worst location, which depends on the shape found in phase 1:
- Page per subject → give that one page the two sections below.
- One big file → add a block at the top and leave everything
else beneath it. No new files, no folder structure.
- Daily notes only → create one file holding current values, and leave every
journal entry untouched. The journal was already correct.
- Not markdown → do not restructure anything. Explain where the current value
should live in the tool they already use, and stop there.
The shape below is the page-per-subject version; adapt the same two ideas to the
others. What has to be true in every case is only this: one place says what is true
now, and it gets replaced rather than added to.
markdown
## Current State
<!-- One entry per subject. Dated. REPLACED on update, never appended to. -->
- **Retainer** (2026-08-01): $3,200/mo, renewed through February 2027
- **Main contact** (2026-05-02): Curtis Ilo
## Log
<!-- Append-only. Never edit or delete an entry. -->
- (2026-04-30) Delivered and paid, $21,000
- (2026-05-02) Retainer started at $2,800/mo
- (2026-06-15) Added reply drafting, retainer to $3,200/mo
Conversion rules, in order of importance:
- Lose nothing. Every existing line lands in one of the two sections, verbatim.
This is sorting, not rewriting. Improving the prose is how information disappears
without anyone noticing.
- One entry per subject in Current State. Where two lines describe the same
current value, the newer wins and the older moves to the Log. Where the order is
unclear, ask. Never guess.
- Date every Current State entry. Ask for a missing date or take it from file
history. An undated current value is barely better than a stale one.
- Never merge two subjects that merely look similar. "Acme (May)" and "Acme Corp
renewal" may be genuinely different things. A duplicate entry is a cheap mistake;
a wrong merge destroys information. Report near-misses and let the user decide.
- Show a diff and get approval before writing.
Re-ask the earlier question afterwards so the correct answer is visible. Same notes,
same agent, one page restructured.
Phase 7: change the write path
This phase decides whether the audit was worth anything. Converting pages fixes
today; changing how facts get written is what stops the recurrence.
Add to whatever file instructs the agent (
,
, a system prompt):
markdown
## Writing to these notes
Every fact is state or event.
- **State** (one current value that changes: price, status, owner, date):
find the matching line in `## Current State` and REPLACE it. Always date it.
Never add a second line for the same subject.
- **Event** (a thing that happened): append to `## Log`. Never edit or delete
an existing Log entry.
If unsure, append to the Log and say so. A missing state update is recoverable;
a rewritten history is not.
Then state the honest part: this instruction gets followed most of the time, not all
of the time. Anything that must happen every time needs a mechanism. Two cheap ones
worth more than the instruction:
- Re-run this audit on a schedule and watch whether the count climbs.
- Stamp dates with a script after the fact instead of asking for them.
Set expectations honestly
Restructuring alone often moves the number less than people expect. When it does not
move, the reason is usually that the correct fact was never captured, and no amount
of reorganizing reaches a fact nobody wrote down. Say that when it applies. The
audit's real value is identifying which of the two problems is in play.
Resources
- : run it for the deterministic scan; lists all flags,
returns structured findings. Never read it into context; only its output.