second-brain-audit

セカンドブレイン監査

ノートは特定の形で古くなります。破損することも、消えることもありません。ただ、ある事実がいつの間にか真実でなくなり、ノートにはその記述が残り、誰もそれに気づきません。

原因はほぼいつも同じです。**書き込みの経路が追記しかできません。**新しい情報が届くと、古い行の下に新しい行として追加されます。これは一部の事実には適切ですが、別の事実には致命的です。

ひとつの考え方

保存される事実は、次の2種類のいずれかです。

	意味	適切な更新方法
状態	現在の値がひとつあり、それが変化する	置き換える
イベント	起きたことを記録した、タイムスタンプ付きの事柄	追記する

価格、ステータス、担当者、期限は状態です。支払い、署名、決定、学んだ教訓はイベントです。

更新ルールは正反対です。イベントを置き換えると履歴が失われます。状態を追記すると、どちらが現在の値なのか示されないまま、ひとつの問いに対する答えが2つ生まれます。そして古い情報はたいていファイルの上のほうにあるため、先に読まれてしまいます。

**このルールを担うのは指示ではなく、構造です。**古い項目を更新するようモデルや人に頼んでも、気づかれないまま、何度も失敗します。ページを2つのセクションに分ければ、事実をどこに置くかによってルールに従えます。

フェーズ1：形を把握する

**Wiki、保管庫、ページがあると決めつけないでください。**そのどれもない人がほとんどです。監査で確認できる範囲も、適切な修正方法も変わるため、まず実際にあるものを確認してください。

形態	例	状態を置く場所
対象ごとにページがある	clients/acme.md、projects/x.md	各ページに2つのセクション
大きなファイルが1つある	notes.md または CLAUDE.md が1つ	ファイルの先頭にある ## Current State ブロック
日次ノートのみ	2026-06-01.md など、それ以外はない	**変換するものはありません。**状態を記録する層がまったくありません
Markdownではない	Notion、Apple Notes、チャットアシスタントのメモリ	考え方は当てはまりますが、ツールは対応しません

この実行時に指定されたノートフォルダーは $notes で、省略可能です （/second-brain-audit ~/notes）。実際のパスであれば使用してください。何も渡されず、上の行にまだ \$notes と表示されている場合は、作業ディレクトリを使い、ユーザーに確認してください。存在しないパスの場合は、その旨を伝えて停止し、誤ったフォルダーを監査しないでください。

次に、以下の2点を確認してください。

1. **ノートの保存場所。**スキャン対象となるMarkdownフォルダーです。
2. エージェントが毎回のセッションで読み込むもの。CLAUDE.md、MEMORY.md、システムプロンプトファイルなど、自動的に読み込まれるものです。これが何より重要です。アーカイブ内の古い情報は無害ですが、常に読み込まれるファイルに同じ情報があると、それが問題になります。ユーザーが把握していない場合はその旨を伝え、それを対象にせず実行してください。

日次ノートしかないケースは、特に明確に伝える価値があります。日付付きノートはイベントログであり、イベントは蓄積されるものなので、何も間違っていません。欠けているのは、今何が真実なのかを示す場所です。日記を再構成するよう勧めるのは、かえって間違いです。

フェーズ 2：常時読み込まれる範囲を監査する

これは、ツールや分野を問わず、スクリプトの有無にかかわらず、あらゆるセカンドブレインで機能する部分です。 スキャンで十分な量が見つかった場合でも、必ず実行してください。

エージェントが毎回のセッションで読む内容は少量です。だからこそ、常に読み込めます。そのため、全体を読み、主張を一つずつ確認できます。

1. その範囲をすべて読む。 常時読み込まれるファイル、大きなファイルの冒頭、またはピン留めされたページなどです。すべて読みます。そして、実際に全体が届いているか確認します。フックやコンテキスト予算によって、通常は末尾から切り捨てられます。ディスク上では「常に読み込まれる」ファイルでも、エージェントには最古の3分の1しか届かないことがあります。実際に届く内容を監査し、切り捨て自体も指摘事項として扱ってください。
2. 状態を示す主張をすべて抽出する。 現在の事実として表現されているものです。ステータス、担当者、料金、バージョン、期限、「現在」「使用している」「にある」などです。出来事として表現されているものは無視してください。出来事は真実であり続けるためです。
3. 各主張について、ノート全体から最新の証拠を探す。 対象を grep し、その対象に言及している最新のファイルを読みます。
4. 各主張を次の3つに分類する。
   • 確認済み。 詳細が一致しています。
   • 矛盾あり。 より新しい情報と食い違っています。これは情報の劣化であり、最も重要な指摘事項です。
   • 裏付けなし。 どこにも裏付けがありません。多くの場合、その主張はかつては正しかったものの、証拠が記録されなかったということです。それを明言する価値があります。

主張が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 を指定してください。各対象は1語にします（"Hourly rate" ではなく rate）。構造化された出力には --json を指定します。小規模なフォルダーでは、スクリプトはページ名と太字のキーだけを基に値を割り当てるため、--subject を指定しないと、実際にはファイル間に矛盾があっても、警告なしでゼロと判定されることがあります。スクリプトは数を数えます。監査を行うのはフェーズ 2 です。スクリプトは読み取りのみを行い、書き込みは一切しません。

ゼロでも問題がないとは限りません。 推測せずに比較できるのは値だけです。そのため、金銭情報のないノートはほとんど検出されず、金額が変わらないままステータスだけが変わった場合も検出できません（「支払期限：$32,300」と「保留中：$32,300」は同じ数値です）。「0 touch a file your agent loads」という行は金銭情報のみを集計します。常時読み込まれるファイルはフェーズ 2 で監査され、この集計の対象ではありません。スクリプトは検出できないことがわかると COVERAGE WARNING を出力します。「問題は見つかりませんでした」と報告するのではなく、その警告を読み上げてください。

そもそもなぜスクリプトを使うのか： 集計結果は、2回実行しても同じでなければなりません。600個の箇条書きの集計をモデルに依頼すると、自信ありげに数を返しますが、翌日には異なる数を返すことがあります。これは、このスキルで防ごうとしている種類の失敗です。スクリプトが数を数え、エージェントが判断します。

フェーズ 4：どちらにも見えないものを読む

フラグが付いたページをいくつか開き、正規表現では見つけられない問題を探します。

• ライフサイクルの矛盾。「来週ローンチ」と書かれたページがある一方で、3 か月前のログにはプロジェクトが中止されたと記録されているケースです。数値に食い違いはないため何もフラグが付かず、内容は完全に間違っています。
• **そもそも書き留められていない事実。**間違った回答の最も一般的な原因は、整理が不十分なことではありません。真の値が会話や日報にしか存在したことがない、ということです。再整理してもそこにはたどり着けません。再構成が役立つかのように示すのではなく、そうはっきり伝えましょう。
• **手を加えてはいけないページ。**チェックリスト、参照リスト、持ち物リストなどです。これらは意図的にリスト形式になっています。形式を変えると有用性が損なわれますが、構造チェックにはすべて合格してしまいます。
• **2 つの正しい行に、実現不可能なスケジュール。**各「Current State」の行はそれぞれの対象と照合されますが、2 つの行同士は照合されません。2 つのキーに「9/23 公開」とある場合、本当に矛盾しているのか、共通のホスト動画を指しているのかは不明です。どちらなのか行に明記すべきです。ブロック内で日付の繰り返しを grep しましょう。
• **確認されていない値に、新しい日付が付いている。**単に移動しただけの行の日付を更新する書き換えや、数か月前に作成された表に「本日、全行を確認済み」と記すことは、古い値に、それを見抜けたはずの唯一の手がかりを与えてしまいます。日付を信用する前に、日付を新しくした行について git blame の結果を確認しましょう。日付は値を確認したという主張であり、行を編集したという印ではありません。
• **キーの増殖。**1 つの対象が複数の「Current State」キーに分散している状態です（「Brief 10050 draft」、「Brief 10050 review pass」、「Brief 10050 record day」など）。キーはすべて異なるため重複チェックには合格しますが、その中で最も新しいものも古いままかもしれません。重複キーの不具合とは逆の問題ですが、対処法は同じです。問題として報告し、統合するかどうかは所有者に委ねましょう。

フェーズ 5：報告する

ツールの出力を要約するのではなく、最も深刻な指摘を最初に伝えます。

Acme が支払う金額について回答が 3 つあり、最も古いものはエージェントが毎回のセッションで読むファイルにあります。

エージェントがすでにこれらのメモを使っている場合は、実際に動作を見せましょう。メモに答えがあるはずの質問をして、返答を読み上げます。3 月にすでに事実ではなくなった金額を、アシスタントが自信満々に返すのを見るほうが、どんな報告書よりも強く伝わります。よくある「熱心に確認しているのに、間違ったまま」というケースも指摘しましょう。ページを確認して別のファイルが古そうだと警告する一方で、真の値が永続的な場所に一度も記録されていないため、結局その値を見落とすケースです。

小さなフォルダーなら、有能なエージェントはすべてを読み、真実を見つけます。実際に毎回のセッションでエージェントに渡されるものだけにデモを絞りましょう（常時読み込まれるファイルだけを貼り付けるか、読み取りツールを無効にして実行します）。そして、もう一度質問します。2 つの回答の差が、指摘すべき問題です。

フェーズ 6：1 か所を修正する

一括変換はせず、ユーザーが同意していないページも変換しないでください。フェーズ 1 で見つかった構成に応じて、最も問題のある場所を 1 つだけ修正します。

• 件名ごとのページ → そのページ 1 つに、以下の 2 つのセクションを追加します。
• エージェントが毎回読み込むインデックス（MEMORY.md、ピン留めされた要約など） → 何と呼ばれていようと、それは状態です。日付付きの ## Current State ブロックを最上部に置き、切り捨てられても残るようにします。各行を案件ごとに整理し、古くなった行はそのまま ## Log の末尾に移動します。ToDo リストはその間に残します。
• 1 つの大きなファイル → ## Current State ブロックを最上部に追加し、それ以外はすべてその下に残します。新しいファイルもフォルダー構造も作りません。ファイルにすでに現在の状態を示すブロック（「Current status」「Now」「Active」など）がある場合、その行はルール 2 に従って新しいブロックか Log に移動します。現在を示すセクションが 2 つあることが、解消すべき問題です。古いブロックは決して残さないでください。
• 日次メモのみ → 現在の値を記録するファイルを1 つ作成し、日誌の各項目には手を加えません。日誌はすでに正しい状態です。
• Markdown 以外 → 構成を変更しないでください。現在の値を、すでに使用しているツールのどこに記載すべきか説明し、そこで終了します。

以下の構成は、件名ごとのページの場合です。同じ 2 つの考え方を他の場合にも適用してください。すべての場合に必要なのは、現在の事実を示す場所が 1 つだけあり、追加ではなく置き換えられることです。

## 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 つのセクションのどちらかに一字一句そのまま入れます。これは分類であり、書き直しではありません。文章を改善しようとすると、誰にも気づかれずに情報が失われます。
2. Current State には件名ごとに 1 項目だけ記載します。 2 つの行が同じ現在の値を示している場合は、新しい方を残し、古い方を Log に移します。順序が不明な場合は質問してください。決して推測しないでください。
3. Current State のすべての項目に日付を付けます。 日付がなければ確認するか、ファイルの履歴から取得してください。日付のない現在の値は、古い値よりわずかにましなだけです。移動した行の日付は、その行自身の日付であり、今日の日付ではありません。日付を付けることは、その値を確認したという主張になります。移動しただけでは何も確認していません。
4. 似ているだけの 2 つの件名を決して統合しないでください。 「Acme（5 月）」と「Acme Corp の更新」は、本当に別の事柄かもしれません。重複項目は小さなミスで済みますが、誤った統合は情報を壊します。紛らわしい例を報告し、判断はユーザーに委ねてください。
5. 書き込む前に差分を提示し、承認を得ます。

その後、正しい回答が見えるように、先ほどの質問をもう一度してください。同じメモ、同じエージェント、再構成した 1 つのページです。次に、まだ対応が必要なことを記録します。これがフェーズ 8 です。そうしなければ、次の実行は何もない状態から始まります。

フェーズ 7：書き込み方法を変更する

このフェーズで、監査に意味があったかどうかが決まります。ページを変換すれば今日の問題は直りますが、事実の書き込み方法を変えることで、再発を防ぎます。

エージェントへの指示を記載しているファイル（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.

続けて、実情も伝えてください。この指示はほとんどの場合に守られますが、常に守られるわけではありません。毎回必ず実行する必要があるものには、仕組みが必要です。この指示よりも効果のある、簡単な仕組みを 2 つ紹介します。

• 定期的にこの監査を再実行し、件数が増えていないか確認します。フェーズ 8 によって、この比較が可能になります。確認する件数は、フェーズ 2 で見つかった矛盾のある項目です。正しく修正した後でも、スクリプトの合計件数が増えることがあります。「支払い済み」や「完了」と記載された Current State の行が、未完了リストの正規表現に一致するためです。
• 日付を尋ねるのではなく、後からスクリプトで日付を付けます。
• 再生成できる列（フォージ上のリポジトリの公開範囲、パッケージファイル内のバージョンなど）は、手入力せずに再生成します。誰も確認しない値は 3 か月以内に誤った値になり、その確認は、問題を発見する監査より低コストです。

フェーズ 8：調査結果を確実に残す

ここまでの内容は、すべて会話の中にしかありません。ウィンドウを閉じれば、 監査は消えてしまいます。情報の山、主張、たどり着けなかった場所もすべてです。 これは、このスキル全体が扱っている問題と同じ失敗を、このスキル自体が犯しているということです。

ですから、教えている形式で書き留めてください。ノートフォルダーに second-brain-audit.mdという1つのファイルを作成します。

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

このファイルには4つのルールがあります。

1. **各場所をキーにします。**修正する場合は、その場所の行を置き換えます。1つの場所に対して 2行目を作ってはいけません。
2. **各実行結果は、矛盾の件数を含む1つのログエントリにします。**この件数が、時間の経過とともに 確認する数値です。増加しているなら、書き込み経路が機能していません。
3. **毎回読み込まれるものには含めません。**これは作業キューであり、ビジネスに関する事実では ありません。また、古くなった主張をそのまま引用しています。
4. 次に別の何かがこれを読み込みます。/second-brain-fixがキューを まとめて処理し、後の監査ではログを読み、件数が変化したかを確認します。後の実行で さらに深刻な問題が見つからない限り、NEXTとマークされた項目から修正を始めます。

audit.pyは、名前がsecond-brain-auditで始まるファイルをスキップするため、 後のスキャンでレポートが証拠として再び検出されることはありません。

それから、修正ツールに引き継ぐ

最後に、これを声に出して伝えてください。すべてのユーザーが抱く疑問であり、答えは 「これをもう一度実行してください」ではないからです。

監査では、形式がわかるように1つの場所を修正しました。残りを処理するには、 /second-brain-fixを実行するか、別の場所から/second-brain-fix <path to this file>を実行してください。 同じファイルを読み込み、調査結果をまとめて処理しながら、台帳を更新していきます。

一度に1つの場所を修正するのは、このスキルとしては正しい方法ですが、計画としては役に立ちません。 誰も7フェーズの監査を40回も実行しません。バッチ処理は別の契約を持つため、別のスキルです。 こちらのスキルは一括変換をせず、すべての書き込みに差分確認を必須とします。一方、あちらのスキルは 一度に多数のファイルを書き込み、開始前にブランチかコピーを用意する必要があります。

対象範囲に問題がなくなったら終了する

すべてのページを変換するような終わり方はありません。それを追い求めると、 2週目には人がやめてしまいます。目指す状態は限定的です。**エージェントが毎回読み込む内容に、 矛盾がないこと。**古いページがたくさん残るアーカイブは、腐敗ではなく歴史です。 より深い階層のページを変換するのは、ある主題について時間をかけて複数の記録が蓄積されている場合や、 誤った回答が繰り返し出る場合に限ります。

期待値を誠実に伝える

再構成だけでは、数値が期待したほど下がらないことがよくあります。数値が下がらない場合、 たいていの原因は、正しい事実がそもそも記録されていないことです。誰も書き留めなかった事実には、 どれだけ整理し直してもたどり着けません。該当する場合は、そのことを伝えてください。 監査の本当の価値は、2つの問題のうち、どちらが起きているかを特定することです。

リソース

• scripts/audit.py：決定論的なスキャンを実行します。--helpで全フラグを確認でき、 --jsonは構造化された調査結果を返します。コンテキストに読み込まず、出力だけを確認してください。