# Second Brain Audit > Audit any second brain, notes folder, or agent memory for facts that have quietly stopped being true, then fix the worst one so it stops recurring. Works on a wiki, a single notes file, daily notes, or a non-markdown tool, and adapts the fix to whichever it finds. Checks every current-sounding claim in whatever the agent loads each session against the freshest evidence, and separates contradicted… - **Type:** Skill - **Install:** `agentstack add skill-coleam00-skills-second-brain-audit` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [coleam00](https://agentstack.voostack.com/s/coleam00) - **Installs:** 0 - **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [coleam00](https://github.com/coleam00) - **Source:** https://github.com/coleam00/skills/tree/main/.claude/skills/second-brain-audit ## Install ```sh agentstack add skill-coleam00-skills-second-brain-audit ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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** | `clients/acme.md`, `projects/x.md` | two sections on each page | | **One big file** | a single `notes.md` or `CLAUDE.md` | a `## Current State` block at the top | | **Daily notes only** | `2026-06-01.md`, 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: 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. 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. ```bash python /scripts/audit.py \ --always-loaded MEMORY.md --always-loaded CLAUDE.md ``` Pass `--subject "Acme Corp"` to track named subjects by name, and `--json` 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 `## Current State` 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 - **Retainer** (2026-08-01): $3,200/mo, renewed through February 2027 - **Main contact** (2026-05-02): Curtis Ilo ## Log - (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: 1. **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. 2. **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. 3. **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. 4. **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. 5. **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 (`CLAUDE.md`, `AGENTS.md`, 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 - `scripts/audit.py`: run it for the deterministic scan; `--help` lists all flags, `--json` returns structured findings. Never read it into context; only its output. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [coleam00](https://github.com/coleam00) - **Source:** [coleam00/skills](https://github.com/coleam00/skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-coleam00-skills-second-brain-audit - Seller: https://agentstack.voostack.com/s/coleam00 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.