second-brain-audit

Second Brain Audit

笔记会以一种特定的方式逐渐失效：没有内容损坏，也没有东西丢失；只是某条事实不再成立，笔记却仍然这么写，而且没有任何提示。

原因几乎总是相同的：写入路径只能追加。 新信息到来后，会作为新的一行加在旧内容下面。对某些事实来说，这样做是对的；对另一些事实来说，却会造成严重问题。

核心理念

每条存储的事实都属于以下两种类型之一。

	含义	正确的更新方式
状态	一个当前值，并且会改变	替换它
事件	一件有时间戳且已经发生的事	追加它

价格、状态、负责人、截止日期：这些是状态。付款、签名、决策、学到的经验：这些是事件。

更新规则恰好相反。替换事件会破坏历史记录。追加状态会让同一个问题出现两个答案，却没有标明哪个才是当前值；而过时的副本通常位于文件较靠前的位置，因此会先被读到。

规则应由结构承载，而不是依赖指示。 要求模型或人记得更新旧条目，会悄无声息地、反复地失败。给页面划分两个部分，事实落在哪个部分，就能自然遵循相应规则。

阶段 1：明确结构

不要假设用户有 wiki、知识库或页面。 大多数人都没有。先查看实际存在的内容，因为这会影响审计能发现什么，也会影响应该如何修复。

结构	示例	状态应存放的位置
每个主题单独一页	clients/acme.md、projects/x.md	每页设置两个部分
一个大文件	单个 notes.md 或 CLAUDE.md	顶部添加 ## Current State 区块
仅有每日笔记	2026-06-01.md，除此之外没有其他内容	无需转换。 完全缺少状态层
非 Markdown 格式	Notion、Apple Notes、聊天助手的记忆	这个理念仍然适用；工具则不适用

本次运行时指定的笔记文件夹是 $notes，它是可选的 （/second-brain-audit ~/notes）。如果它是一个有效路径，就使用该路径。如果没有传入路径，因此上方仍显示 \$notes，则使用工作目录并向用户确认。如果传入的路径不存在，应说明这一点并停止，而不是审计错误的文件夹。

接着确认两件事：

1. 笔记存放的位置。 扫描所需的 Markdown 文件夹。
2. Agent 每次会话都会读取的内容。 CLAUDE.md、MEMORY.md、系统提示词文件，或任何自动加载的内容。这一点比其他任何事情都重要：归档中的过时事实无伤大雅；同一条事实若出现在每次都会加载的文件中，就是问题所在。如果用户不清楚，应如实说明，并在不包含该文件的情况下运行。

仅有每日笔记的情况最值得明确指出。带日期的笔记是事件日志，事件本来就应该不断累积；它们没有任何问题。缺少的是一个能说明当前情况的地方。建议用户重构日志，反而是完全错误的做法。

阶段 2：审计始终加载的内容

这部分适用于每个第二大脑，无论使用什么工具、什么领域，也无论有没有脚本。 始终执行这一步，即使扫描发现了很多问题。

Agent 每次会话都会读取的内容很少：正因如此，它才能始终加载。因此可以完整阅读， 逐条核查其中的说法。

1. 完整阅读这部分内容。 始终加载的文件、大文件的开头，或置顶页面。全部读完。然后检查它是否确实完整送达：钩子和上下文预算会截断内容，通常从底部开始截断；磁盘上“始终加载”的文件送到 Agent 那里时，可能只剩最早的三分之一。审计实际送达的内容，并将截断本身视为一项发现。
2. 提取所有描述状态的说法。 任何表述为当前事实的内容：状态、负责人、费率、版本、截止日期、“目前”、“我们使用”或“位于”。忽略表述为事件的内容，因为事件始终为真。
3. 逐条寻找每项说法的最新证据。 在笔记的任何位置搜索相关主题。阅读提到它的最新文件。
4. 将每项说法分为三类：
   • 已确认。 细节一致。
   • 存在矛盾。 有更新的内容与之不符。这就是信息腐坏，也是首要发现。
   • 缺乏依据。 没有任何内容能支持它。很多时候，这项说法曾经属实，只是从未记录证据；这点值得明确说出来。

10 到 30 项说法很常见，审查只需几分钟。没有资金信息的研究资料库、个人 Wiki、Notion 工作区：都可以用这种方式审计，而且脚本无法审计它们。

先报告存在矛盾的内容，再报告缺乏依据的内容。两者都是审查发现。

阶段 3：如果笔记适用，则运行扫描

这是加速工具，不是审计。它适用于事实包含货币数值的 Markdown 文件夹，查找跨文件分歧的速度远快于逐篇阅读。 否则跳过；阶段 2 已经完成了审查工作。

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

对每个你关心的主题都传入 --subject，每个主题只用一个词（用 rate，而不是 "Hourly rate"），并传入 --json 以获取结构化输出。在较小的文件夹中，脚本只根据页面名称和加粗键名归类数值，因此不传入 --subject 时，真实的跨文件矛盾可能会被漏掉，结果显示为零且没有警告。脚本负责计数；阶段 2 才是审计。脚本只读取内容，绝不写入。

零不代表一切正常。 在不猜测的情况下，脚本只能比较数值；因此，其中没有资金信息的笔记基本不会被它发现；金额不变但状态发生变化的情况也一样（“$32,300 待付”和“$32,300 暂缓”是同一个数字）。它显示的“0 touch a file your agent loads”一行只统计金额；始终加载的文件应在阶段 2 审计，而不会计入这个数字。脚本发现自身存在盲区时会打印 COVERAGE WARNING。请读出这条警告，而不要报告“未发现问题”。

为什么要用脚本： 计数结果必须前后一致。让模型统计 600 条要点，它今天会给出一个自信的数字，明天却给出另一个；这正是这项技能要解决的一类失误。脚本负责计数，Agent 负责判断。

阶段 4：读取双方都看不到的内容

打开几篇标记出来的页面，找出正则表达式无法发现的问题：

• 生命周期冲突。 某个页面写着“下周启动”，而三个月前的一条日志却记录项目已取消。没有数字不一致，因此不会标记出来，但内容完全错误。
• 从未记录下来的事实。 错误答案最常见的原因不是组织不善，而是真实值只存在于对话或每日记录中。重新整理也无法触及它。请直言这一点，不要暗示重组会有所帮助。
• 不得修改的页面。 清单、参考列表、打包清单。它们本来就是列表。转换它们会破坏其用途，而且所有结构检查仍会通过。
• 两条都正确，却排出不可能的日程。 每条当前状态都只会针对各自的主题进行检查；没有检查两条内容是否互相矛盾。两个键上都写着“9/23 上线”的两个交付项，要么确实冲突，要么共用一个主持人视频，应该说明是哪种情况。在该区块中搜索重复日期。
• 未经核验的值被标上新日期。 重写时给仅仅移动过的行重新标日期，或在数月前创建的表格上方写一句“今日已核验各行”，都会给过时的值加上唯一一个原本能暴露它的问题。信任日期前，先查看 git blame 对刚标日期的行显示了什么；日期代表该值已核验，而不是这行被改动过的标记。
• 键名过度分散。 一个主题分散在多个当前状态键中（“Brief 10050 草稿”“Brief 10050 审阅轮次”“Brief 10050 录制日”）。每个键都不重复，因此重复检查会通过，而其中最新的一项仍可能过时。这与重复键问题正好相反，但解决办法相同：每个具有单一状态的事项只设一个键。报告此问题；是否合并由所有者决定。

阶段 5：报告

先说影响最大的那一项发现，而不是概述工具的输出：

Acme 的付款金额有三个不同答案，而最旧的那个就在 Agent 每次会话都会读取的文件中。

如果已有 Agent 基于这些笔记运行，就实际演示。提出笔记本应能回答的问题，并读出回复。看着助手自信地给出一个早在 3 月就已失效的数字，远比任何报告都更有冲击力。指出常见情况：它尽职尽责，却仍然答错——它检查了一页内容，警告另一份文件看起来过时，却依然没能找到真实值，因为这个值从未被写入任何持久记录。

在规模较小的文件夹中，能力足够强的 Agent 会读取所有内容并找到真相。请将演示限定在 Agent 每次会话实际收到的内容（只粘贴始终加载的文件，或关闭读取工具运行），然后再次提问。两次答案之间的差距就是发现的问题。

阶段 6：修复一个位置

绝不批量转换，也绝不转换用户未同意转换的页面。修复问题最严重的位置，具体取决于阶段 1 发现的结构：

• 每个主题对应一个页面 → 给那一个页面添加下面的两个章节。
• Agent 每次会话都会加载的索引（MEMORY.md、置顶摘要）→ 不管它叫什么，它都是状态信息。在最顶部放置一个带日期的 ## 当前状态 区块，按事项标记每一行，并将已被取代的行原封不动地移至底部的 ## 日志。待办列表保留在两者之间。
• 一个大文件 → 在顶部添加一个 ## 当前状态 区块，其余内容全部保留在下面。不新建文件，不创建文件夹结构。如果文件中已有一个声称记录当前情况的区块（“当前状态”“现在”“进行中”），则按规则 2 将其中的行移入新区块或日志。两个章节都声称记录现在的情况，正是你要消除的问题，所以绝不要保留旧区块。
• 只有每日笔记 → 创建一个文件来存放当前值，并保持每条日志原封不动。日志原本就是正确的。
• 不是 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

转换规则，按重要性排序：

1. 不遗漏任何内容。 每一条现有内容都必须原封不动地归入两个章节之一。这是分类，不是改写。润色文字会让信息悄无声息地消失。
2. 当前状态中每个主题只保留一条记录。 如果两行描述的是同一个当前值，以较新的一行为准，并将较旧的一行移至日志。如果顺序不明确，就询问。绝不猜测。
3. 为当前状态中的每条记录标注日期。 询问缺失的日期，或从文件历史中获取。未注明日期的当前值几乎不比过时信息好。被移动行上的日期应是该行自身的日期，而不是今天：标注日期意味着声称该值已经过核实，而移动行并不代表核实了任何内容。
4. 绝不合并仅仅看起来相似的两个主题。 “Acme（5 月）”和“Acme Corp 续约”可能确实是不同的事项。重复记录是小错误；错误合并则会毁掉信息。报告看似相同但其实不同的条目，让用户决定。
5. 先展示差异并获得批准，然后再写入。

之后重新询问之前的问题，让正确答案清晰可见。同样的笔记、同一个 Agent，只重组一个页面。然后记录仍未解决的事项，这就是阶段 8 的工作，否则下一次运行就会从零开始。

阶段 7：更改写入路径

这一阶段决定审计是否有价值。转换页面能解决今天的问题；改变事实的写入方式，才能阻止问题重现。

将以下内容添加到任何用于指示 Agent 的文件中（CLAUDE.md、AGENTS.md、系统提示词）：

## 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.

然后如实说明：这条指示大多数时候会得到遵循，但并非总是如此。任何必须每次都发生的事情，都需要一种机制。以下两种成本低廉的做法比这条指示更有效：

• 按计划重新运行此审计，并观察计数是否上升。阶段 8 可让这种比较成为可能。需要关注的计数是阶段 2 中相互矛盾的那一堆。修复正确后，脚本的总数也可能上升，因为当前状态中写着“已付款”或“已完成”的行会匹配其未结事项正则表达式。
• 事后用脚本加上日期，而不是要求用户提供日期。
• 重新生成任何可以重新生成的列（例如，从代码托管平台获取仓库可见性，从包文件获取版本），而不是手动输入。无人核查的值会在一个季度内出错，而核查的成本低于发现问题的审计。

第 8 阶段：把发现记录在可靠的地方

到这里为止的所有内容都只存在于对话中。关闭窗口，审计结果就消失了：那些堆积的内容、那些说法、那些你还没查到的地方。这正是整个技能要解决的问题，却被技能本身重蹈覆辙。

所以，把它写下来，按这里教的形式。笔记文件夹中只创建一个文件，名为 second-brain-audit.md：

# Second brain audit

## Current State


- **MEMORY.md** (2026-09-18): the always-loaded file. 6 contradicted, 3 unsupported.
  FIXED this run, `## Current State` block added at the top, 9 superseded lines to `## Log`.
- **clients/acme.md** (2026-09-18): 4 contradicted, all about the retainer. NEXT.
- **notes/tools.md** (2026-09-18): 2 unsupported, no trail, low value. Leave it.
- **write path** (2026-09-18): rule added to `CLAUDE.md`.

## Log


- (2026-09-18) First run. 24 claims in the always-loaded file: 13 confirmed,
  6 contradicted, 5 unsupported. Fixed MEMORY.md. Asked "what do we charge Acme?"
  before and after, and got $4,000 then $9,500.

这个文件有四条规则：

1. 每个位置都是一个键。 修正该位置时，替换对应行。绝不要为同一个位置另起一行。
2. 每次运行记录为一条 Log 条目，并附上被证伪的数量。这个数量是需要长期关注的指标。如果它上升，说明写入流程未能奏效。
3. 不要把它放进每次会话都会加载的内容里。 它是工作队列，不是关于业务的事实，而且其中逐字引用了过时的说法。
4. 之后要有别的东西读取它。 /second-brain-fix 会分批处理队列，之后的审计会读取 Log，查看数量是否变化。除非后续运行发现了更严重的问题，否则标记为 NEXT 的位置就是修复的起点。

audit.py 会跳过所有名称以 second-brain-audit 开头的文件，因此这份报告不会在之后的扫描中再次被当作证据。

然后交给修复工具

结束时，请大声说出下面这段话，因为这是每位用户都会问的问题，而答案不是“再运行一次”：

这次审计修复了一个位置，让你了解整体形式。要处理其余问题，请运行 /second-brain-fix，或者从其他位置运行 /second-brain-fix <path to this file>。它会读取 同一个文件，分批处理发现的问题，并在处理过程中更新台账。

一次只修复一个位置，对这个技能来说是正确的做法，但作为计划毫无用处。没人会把七阶段审计跑四十遍。批量任务是独立的技能，因为它遵循不同的约定：这个技能绝不会批量转换，并且每次写入都必须先通过差异检查；而那个技能会一次写入多个文件，并要求开始前先创建分支或副本。

表面内容干净后就停止

不可能把所有页面都转换一遍，一味追求这一点会让人第二周就放弃。完成标准很明确：Agent 每次会话加载的内容中，没有任何被证伪的说法。 充满旧页面的档案不是腐朽，而是历史记录。只有当某个更深层页面留下了脉络（随着时间推移，有多条关于同一主题的记录），或它不断导致错误回答时，才转换它。

如实设定预期

单靠重组，数字的下降幅度往往不如人们预期。如果数字没有变化，通常是因为正确的事实从未被记录下来；无论怎样重新整理，都无法找到没人写下的事实。遇到这种情况时，请如实说明。审计的真正价值，在于指出这两类问题中究竟是哪一类。

资源

• scripts/audit.py：运行它进行确定性扫描；--help 会列出所有标志，--json 会返回结构化发现结果。绝不要将脚本读入上下文；只读取它的输出。