knowledge-base

ナレッジベースパック — ここでの作業方法

このプロジェクトでは、ソースに根拠を置くナレッジベースの構成を採用しています。重要なのは、証拠を閉じたループにすることです。保持されたソースまで追跡可能な経路がなければ、正式な情報として扱えるものはありません。このスキルがワークフローを担うことで、テンプレートと log.md をすっきり保てます。テンプレートからドキュメントを作成すれば構成が整い、作成方法はここに記載されています。

このスキルはパックのガイダンスです。プラットフォームの /open-knowledge スキル（読み取り／書き込み／プレビュー／リンク付け／根拠付けのルール）は、引き続きすべての Markdown 操作に適用されます。このスキルは、その上にナレッジベースのワークフローを重ねます。

作成時にリンクする

ユーザーは作業の進行をリアルタイムで見ています。エディターは書き込み中のファイルを表示し、ページがリンクされるたびにナレッジグラフが画面上で組み上がります。表示の管理は不要です。ページを適切に作成するだけです。すべてのページには、書き始めた時点からリンクを付けます（最低限、ハブ／インデックスページと、最も関連性の高い兄弟ページをリンクします。リンクのないページはグラフに表示されません）。また、関連ページでは cluster: フロントマターの値（例：cluster: architecture）を共有し、グラフのクラスター色分けでマップがひと目でわかるようにします。

3 つのレイヤー

external-sources/   raw sources, saved verbatim     (produced by `ingest`)
      ↓ cite
research/           provisional analysis            (produced by `research`)
      ↓ promote
articles/           canonical, decided knowledge     (produced by `consolidate`)

このループは Karpathy の 3 層ナレッジベースパターンに対応する、取り込み → 調査 → 統合です。下流のあらゆる主張は、上流にある保持済みのソースまでたどれます。external-sources/ 内のローカルパスを引用し、Web URL だけを記載するのは避けてください。ナレッジベースはリンク切れが起きても維持できなければなりません。

Karpathy の洞察：「ナレッジベースの維持で骨の折れる部分は、読むことでも考えることでもなく、記録を管理することです。」人間は、維持にかかるコストが認識される価値を上回ると、Wiki を使わなくなります。こうした手順は、エージェントが疲れることなく記録管理（取得、要約、相互リンク、旧情報の置き換え）を行えるようにするためのものです。相互リンク、後継関係の連鎖、または生ソースの保持を省略すると、有用な Wiki は再び放置されてしまいます。

3 つの手順

各レイヤーには、STOP ゲート付きの完全な手順があり、それぞれ独立したスキルとして提供されるため、必要な作業に応じて読み込まれます。各レイヤーに該当する作業では、OK の動詞に従って手順を実行してください。これらは、単に write するよりもデフォルトで優先する行動です。

手順	配置場所	タイミング
ingest	プラットフォームの /open-knowledge スキル（references/ingest-and-sources.md）。Grounding ルールはあらゆる場面で必要なため、このパックだけでなくすべてのプロジェクトに含まれています。	共有された URL／PDF／ファイルをそのまま保持する場合、またはナレッジベースの主張の根拠にするために URL を取得した場合（バイナリソースを保持し、スクレイピングはしません）。
research	兄弟スキル /research-with-sources	複数のソースを調査／比較／統合し、status: draft と sources: を付けた暫定記事を作成する場合。
consolidate	兄弟スキル /consolidate-notes	実際に決定がなされた場合。status: stable と supersedes: の連鎖を付けて、正式な信頼できる情報源を確定します。

典型的な 2 日目のワークフロー：ユーザーが URL を共有 → ingest（保持）→ ユーザーが「では、これを調査して」と依頼 → research（暫定記事を作成し、必要に応じてソースを追加で取り込み）→ 決定がなされる → consolidate（調査結果を置き換える正式な記事を作成）。

黙って手順を連鎖させないでください。 ingest の後は、research に進むか尋ねてください。research の後は、調査結果を統合する準備ができているか、ユーザーに判断してもらってください。各手順はそれぞれの条件に従って完了し、次の段階へ進むかどうかはユーザーが決めます。

自律性ゲートとセッションレベルの自律性。 手順の STOP ゲート（research の範囲設定ゲート、consolidate の決定確認ゲート）は、セッションレベルの「確認のための質問で作業を止めずに進める」という指示によって無効にはなりません。そうした指示が対象とするのは、「どのファイルのことですか？」といった些細なやり取りです。一方、これらのゲートは、後戻りできない決定のために設けられています。迷った場合は、ゲートの指示を優先してください。

フォルダーごとのルール

external-sources/ — 引用するだけでなく、取得したままのソースを保存します。URLから取得した実際のテキスト、PDFから抽出したテキスト、参照ファイルのコピーが含まれます。各ファイルのフロントマターには、元のURL、アクセス日、著者や発行元のメタデータがあれば記載します。取り込み手順によって作成します（ユーザーからURLを共有された場合も、主張の根拠として自分で取得した場合も同様です）。取得後は変更せず、古くなった取得内容を更新する場合に限り更新します。ここでは分析しません。分析はresearch/に記載します。

research/ — 外部ソースを統合した暫定的な分析を、OKFのstatus: draftとして保存します。/research-with-sourcesスキルによって作成します。すべての事実に関する主張には、external-sources/内の特定の文書（取り込みを省略した場合はインラインURL）を引用します。出典のない主張は記載しません。sources:フロントマターのリストは、本文で実際にリンクされている文書と一致させます。チームが調査結果を確定したら、/consolidate-notesスキルを使ってarticles/に昇格させます。

articles/ — チームの決定後にコミットされ、OKFのstatus: stableとして保存される、正規のナレッジです。/consolidate-notesスキルによって作成します。置き換え対象のresearch/文書へつながるsupersedes:チェーンを持ちます（これらの文書はさらにexternal-sources/を引用します）。これにより、リポジトリの外に出ることなく、完全なエビデンスチェーンを追跡できます。ドメインの信頼できる情報源であり、新しい決定によって置き換えられる場合に限り更新します。

ステータスの遷移

レイヤー	status	設定するタイミング
research/	draft	作成時
articles/	stable	決定後、consolidateによって昇格したとき

新しい記事が調査文書を置き換える場合、その調査文書をstatus: deprecatedに設定し、記事のsupersedes:リストにそのパスを追加して、superseded_by:で記事への参照を設定します。

旧形式との互換性

古いプロジェクトでは、status: provisional / canonicalや、sources:内の文字列エントリが使われている場合があります。これらの形式はそれぞれdraft / stable、ソースリソースとして読み取ります。変更しない文書は書き換えず、新規作成する文書や、すでに更新中のファイルには、上記のOKF形式を使用します。

ログの運用ルール（必須）

プロジェクトのルートにはlog.mdがあります。コンテンツを作成、編集、または再構成したターンの後は、日付入りのエントリを1件追記してください。ファイルごとではなく、ターンごとに1件です。ログを残さない編集は監査証跡を損ないます。

ログには、ingestの実行（新しいソース）、research / consolidateの実行（暫定記事または正規記事）、3つの手順以外で直接行うwrite / edit / move / delete、プロジェクトのオンボーディング実行、フォルダーの再構成、.ok/config.ymlの変更を記録します。

ドキュメントはパスだけでなく、Markdownリンクで参照してください — [path/to/doc](./path/to/doc.md)のように記述すると、links({ kind: "backlinks" })でそのドキュメントのリンクとして表示されます。パス文字列だけではグラフに登録されません。

追記専用の予約済みログであるlog.mdでは、リンク切れがauditから除外されることがあります。brokenLinkSuppressionを含むクリーンな結果が返されても、すべての生のリンクが解決されている証拠ではなく、フィルタリングされたという意味です。リンク切れを解消するために、ログの履歴を書き換えないでください。

エントリの形式：

## YYYY-MM-DD: <short title>

- <what was done>
- Files touched: [doc-a](./path/doc-a.md), [doc-b](./path/doc-b.md)
- Sources ingested: [source-slug](./external-sources/source-slug.md)
- Open follow-ups: <topic-1>, <topic-2>

テンプレート

各フォルダーにはスターターテンプレート（clip、research-log、article）があります。write({ document: { path, template: "<name>" } })で作成します。テンプレートには構造（見出しとフロントマターのひな形）のみが含まれます。各フィールドやセクションの意味は上記で説明しており、ドキュメント本文では繰り返しません。