Second Brain Fix

Second Brain Fix

The audit found what is wrong and fixed one location so the shape was visible. This works through the rest, in batches, from the findings the audit left behind.

The argument

The findings file this run was invoked with is $audit-results, and it is optional:

/second-brain-fix                                   nothing passed
/second-brain-fix ~/notes                           a folder to look in
/second-brain-fix ~/notes/second-brain-audit.md     the findings file itself

$audit-results is a path to one markdown file of findings. /second-brain-audit names what it writes second-brain-audit.md, so that is usually what you will be handed, but the name is not the contract. Any markdown file holding the findings works, and whatever the user points at is the one to use.

Resolve it before anything else:

Never invent a queue from scratch when there are no findings. Auditing and fixing in one pass is how a bulk write happens against findings nobody read.

The findings are the input. $audit-results is both the queue and the record: one keyed line per location in ## Current State, one dated line per run in ## Log. Everything below is driven by that file, and a run that does not update it is a run nobody can pick up from.

This skill writes in bulk. Settle backups before it does.

Never start writing without settling this, and never resolve it by copying the notes folder somewhere else. A duplicate folder of notes is a second answer to every question, which is the exact problem this skill exists to remove.

First, check what is already there. Run git rev-parse --show-toplevel in the notes folder.

• Already in git, either its own repo or tracked by a parent one. Commit or stash anything outstanding, then git checkout -b second-brain-fix, and commit after every batch. Say which repo you are in, because a vault nested inside another project is common and the user should know what the branch covers.

• Not in git. Ask, in these words or close to them:

  Your notes are not in git, so there is no way to undo a batch. Want me to run git init here first? It stays on your machine, nothing gets pushed anywhere, and every batch becomes a checkpoint you can roll back to.

  If they agree: git init, git add -A, one baseline commit, then the branch. Never add a remote and never push.

  If they decline, ask once more and take the answer:

  Understood. To be clear, this rewrites many files at once and there will be no way to undo it. Go ahead anyway?

  On a clear yes, proceed and do not raise it again. On silence or anything ambiguous, stop. An unanswered question is not permission.

The three piles are three different jobs

The middle row is where bulk fixing goes wrong. An unsupported claim has no answer in the notes by definition, so an agent told to "correct these" will invent a value or quietly delete the line. Both are worse than the stale claim.

How much to take on

Ask how large the notes are, or count the markdown files, and scale the ambition:

Bigger notes do not mean convert more. They mean convert a smaller fraction and lean harder on the write path, because at that size nobody is ever going to hand-tend the archive.

Step 1: build the batch list

Read $audit-results. Take the ## Current State entries that are not marked as fixed, plus any pile the audit reported but did not enumerate. Group them into batches of roughly 5 to 15 locations, keeping a folder together where you can.

Show the user the batch list and the order before writing anything. Ordering is always:

1. Whatever loads every session.
2. The pages the agent gets wrong most often.
3. Pages with a trail.
4. Nothing else.

Step 2: the contradicted pile, in batch

For each finding, the newer evidence is already named. So:

• Replace the stale line in ## Current State.
• Move the superseded line, verbatim, to ## Log.
• Date the new line with the date of the evidence, not today.

That last one matters more than it looks. A date on a current value is a claim that somebody checked the value on that day. Stamping today's date on a line you corrected from a note written in June makes a June fact look verified this morning.

Work the whole batch, then show one summary: how many lines replaced, in which files, and the three or four that were least obvious. Do not show a diff per line, and do not ask per line.

Step 3: convert the locations, in batch

Give each page the two sections. Adapt to the shape the audit found:

## 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-06-15) Added reply drafting, retainer to $3,200/mo

One big file gets a ## Current State block at the top and everything else beneath it, no new files. Daily notes get one new file of current values and the journal untouched. Notes that are not markdown do not get converted at all.

This is sorting, not rewriting. Every existing line lands in one of the two sections, verbatim, at most with a date prepended. Improving the prose is how information disappears without anyone noticing, and in a batch nobody is reading closely enough to catch it.

When a bullet has no date and none can be recovered, do not invent one and do not quietly leave the entry bare. Take the date from the evidence if the bullet cites any, otherwise write (date unknown) in the date's place. A bare entry reads as an oversight; (date unknown) reads as the gap it is, and it survives into the next audit as something to ask about.

Two kinds of page to leave alone, and say so rather than converting them:

• Reference checklists. Packing lists, hospital-bag lists, standard operating steps. Few bolded keys, few dates, and the order is the content. Converting one passes every structural check and destroys the thing that made it useful.
• Pages where the freshest status lives inside prose, under a heading that owns the bullets below it. Dissolving that section leaves the newest status outside ## Current State and the oldest inside it, which is the exact failure being removed, rebuilt one level up.