wiki-ingest

Wiki Ingest

ソースを wiki に追加します。ソースを読み、ユーザーと内容を検討し、要約ページを作成し、エンティティ／概念ページを更新して、インデックス、概要、ログを管理します。

事前条件

現在のディレクトリから上位へ向かって、または一般的な wiki の場所（~/wikis/）で SCHEMA.md を検索します。見つからない場合は、まず wiki-init を実行するようユーザーに伝えます。

SCHEMA.md を読み、wiki のルートパス、ページのフロントマター形式、相互参照の規約、ログエントリ形式、インデックスのカテゴリ分類を確認します。

リンクスタイル。 SCHEMA.md の link_style: を読みます。このフィールドがない場合、または <wiki-root>/config/link-style.md が存在しない場合は、obsidian をデフォルトとして、相互参照形式に [[slug]] を使用します。それ以外の場合は、<wiki-root>/config/link-style.md を読み、正確な出力ルールと解析ルールを確認します。以下で記述するすべての相互参照と引用のスラッグターゲットは、そのファイルの ## Emit ルールに従う必要があります。既存ページのスキャン（ステップ 7 のバックリンク監査）はすべて、そのファイルの ## Parse ルールに従う必要があります。

手順

1. ソースを受け取る

ソースは次のいずれかです。

• ファイルパス — ファイルを直接読み、まだ存在しない場合は raw/<filename> にコピーします
• URL — browse スキルを使って取得し、raw/<slug>.<ext> に保存します
• 貼り付けられたテキスト — 提供された内容を使用します

2. ソースを最初から最後まで読む

すべての内容を読みます。長いソースはセクションごとに読みます。読み飛ばしてはいけません。

3. 要点を提示する — 何かを書く前に

ユーザーに次の内容を伝えます。

• 重要な要点を 3～5 個の箇条書きで示します
• ここで新たに登場する、または更新されるエンティティ／概念を示します
• wiki 内の既存情報と矛盾するかどうかを示します（まずインデックスを再生成します — python bin/generate-index.py — 次に wiki/index.md と関連ページを読み、確認します）

次のように尋ねます。「特に強調したい点、または強調を控えたい点はありますか？」

先に進む前に、ユーザーの返答を待ちます。

4. スラッグを生成する

小文字を使い、ハイフンで区切り、特殊文字は使いません。 例：「Attention Is All You Need」→ attention-is-all-you-need

5. ソースの要約ページを作成する

wiki/pages/<slug>.md を作成します。

---
title: <source title>
category: <one of the wiki's Index Categories — e.g. Sources>
summary: <one-line description for the index>
tags: [<relevant tags>]
sources: [<slug>]
created: <today>
updated: <today>
---

# <Source Title>

**Source:** <original URL or file path>
**Date ingested:** <today>
**Type:** <paper | article | transcript | code | other>

## Summary

<2-3 paragraph synthesis — your own words, not abstract copy-paste>

## Key Takeaways

- <bullet>

## Entities & Concepts

<list of entities/concepts as cross-reference links — emit each in the wiki's link_style; see config/link-style.md>

## Relation to Other Wiki Pages

<how this connects to or updates existing knowledge>

5b. 執筆しながら引用を付ける — 省略しない

Summary、Key Takeaways、およびその他の文章セクションを執筆する際は、一般常識ではない事実に関する主張すべてに脚注を付けます。詳しい規約については、SCHEMA.md の Citations セクションを読みます。

引用には 2 種類あり、有効なターゲットは 3 つです。

Quote:     [^N]: <target> <locator> — "<verbatim quote>"
Synthesis: [^N]: <target> <locator> [synthesis] — <what supports the claim>

<target> is one of:
  <slug-reference>     — a source wiki page, written in the wiki's link_style
                         (preferred for the source you're ingesting)
  raw/<file>           — a path, for drive-by citations to other local files
  <URL>                — a live URL or post

取り込み対象のソースについては、スラッグ参照のターゲットを <this-source-slug> とし、config/link-style.md で規定された形式で記述します。wiki-ingest は現在そのページを作成中なので、ページが読み込まれる時点でターゲットは存在しています。

行範囲による出典の明示 — テキストアドレス可能なソースでは必須です。 引用する raw ファイルが Markdown、プレーンテキスト、コード、またはキャッシュされた HTML の場合、そのファイルへのすべての脚注に、意味上の参照位置の後ろに行範囲トークン L<start>-<end>（1 行の場合は L<n>）を付ける必要があります。raw ファイルを読む際、引用する箇所の行番号を記録します。引用の場合は引用元の行、[synthesis] の主張の場合は要約対象の行のまとまりを記録します。例：

[^1]: [[<this-source-slug>]] §3.2 L142-143 — "We employ h = 8 parallel attention layers"
[^2]: [[<this-source-slug>]] §3.2-5.3 [synthesis] L138-202 — encoder/decoder + attention describe the architecture

安定した行番号がないソース（PDF、文字起こし、ローカルにキャッシュされたコピーのないライブ URL）は対象外です。意味上の参照位置（p.N、[HH:MM:SS]、URL アンカー）はそのままにし、L… は省略します。

主張に対してどちらの種類の引用も付けられない場合、それは引用があるとは言えません。引用を見つけるか、主張を弱める（「論文は…と示唆しています」など）か、主張を削除します。

脚注は、すべてのセクションの後、ページの末尾に置きます。最初に参照される順に連番を付けます。

5c. 続行前のセルフチェック

下書きをもう一度読み返します。次の3つの観点で確認してください。

1. 脚注のない主張 — 脚注のない事実に関する主張を探します（長時間の取り込みセッションで最もよくある失敗です）。見つけた主張には脚注を追加するか、表現を修正してください。
2. 行範囲の不足 — 参照先がテキストとして行を特定できる生ファイル（Markdown／プレーンテキスト／コード／キャッシュされた HTML）の脚注すべてについて、L… トークンが含まれていることを確認します。テキストソースの脚注に行範囲がない場合は不完全です。生ファイルに戻って該当する行を探し、トークンを追加してください。対象外のソース（PDF／トランスクリプト／ライブ URL）には必要ありません。
3. リンクの解決 — このページに記述した [[slug]] をすべて集め、それぞれが既存の wiki/pages/<slug>.md または今回の取り込みで作成するページを参照していることを確認します。SCHEMA.md の Concept Identity ルールを参照してください。どちらも参照していない [[slug]] は、実在しないリンクです。削除するか、参照先のページを作成してください。これは wiki-lint が Wiki 全体を対象に実行するリンク切れチェックをインラインで行うものです。今の段階で確認しておけば、リンクグラフを確実に信頼できる状態に保てます。

3つの確認すべてに問題がない場合に限り、エンティティページに進みます。

6. エンティティページと概念ページを更新する

このソースに関係する各エンティティ／概念について、次のように対応します。

• ページが存在する場合： ページを読み、該当するセクションに追記または更新します。frontmatter の sources リストにこのソースを追加し、updated 日付を更新します。
• ページが存在しない場合： ページを作成します。

---
title: <Entity or Concept Name>
category: <one of the wiki's Index Categories — e.g. Entities or Concepts>
summary: <one-line description for the index>
tags: [entity | concept]
sources: [<this-source-slug>]
created: <today>
updated: <today>
---

# <Name>

## Description

<synthesis across all sources that discuss this>

## Appearances in Sources

- <slug-reference to source-slug, in the wiki's link_style> — <one-line note>

## Related Concepts

- <slug-reference to related-slug, in the wiki's link_style> — <relationship>

7. バックリンク監査 — 必ず実施する

wiki/pages/ 内の既存ページをすべて確認し、このソースのエンティティ／概念に言及していて、新しいページへのリンクがまだないページを探します。config/link-style.md の ## Parse 正規表現を使って既存の参照を検出します。同じファイルの ## Emit 形式を使って、新しいページへの相互参照を追加します。

これは最もよく省略される手順です。複利のように価値が増す Wiki の真価は、双方向リンクによって生まれます。

[[slug]] を追加する前に、必ず Concept Identity ルールを適用します。 リンク先は実在するページでなければなりません。ページがあるべきエンティティに言及しているのに、そのページが存在しない場合は、実在しない slug にリンクするのではなく、手順6に従ってページを作成してください。

最終リンク解決チェック。 この取り込みで変更したすべてのページ（要約、エンティティ／概念ページ、バックリンク）を書き終えたら、それらのページにある [[slug]] 参照をすべて集め、それぞれが既存の wiki/pages/<slug>.md を参照していることを確認します。これにより、手順5cのチェック対象を、その後に記述したリンクまで広げます。解決できないリンクがあれば、先に進む前に修正してください。リンクを削除するか、参照先のページを作成します。

7b. 矛盾の確認 — 省略しないでください

この取り込みで触れたすべてのページが作成され、関連ページの内容も把握できたので、コミットする前に矛盾がないか確認します。 規約の詳細については、SCHEMA.md の矛盾の確認セクションを読んでください。これは必須の確認事項であり、注釈ではありません。問題のない取り込みでは、どのページにも矛盾のメタデータは残りません。

対象範囲 — 比較するページ（Wiki全体を読み直さないでください）：

• 作成・編集した各ページとそのページ自身（ページ内の矛盾）
• 作成・編集した各ページと、この取り込みですでに読んだページ（ステップ6のエンティティ／概念ページ、およびステップ7のバックリンク監査で確認した関連ページ）

開いていない離れたページとの矛盾は、ここでは対象外です。定期的なwiki-lintの一括チェックがその補完となります。

見つけた矛盾を分類します：

1. ブロッキング — 同じ範囲における同一エンティティについて、事実に明確な矛盾がある場合：両立しない日付、数値、名称、または相互に排他的な主張（例：新しいソースページではモデルのリリースが2024年とされているが、[[that-model]]では2023年とされている）。ブロッキング矛盾ごとに、影響を受けるページのフロントマターに1行だけ記入します。対象は、今回編集したページのうち、より新しい主張を記載しているページです：

   contradiction-check: failed — launch year conflicts with [[that-model]] (2024 vs 2023)
   

ページ内の矛盾には、[[slug]]の代わりにinternalを使います。その後、**そこで止めてください。コミットの手順（ステップ10）には進まないでください。**矛盾（両方の主張と両方の記載箇所）を示し、ユーザーに次の解決方法を提示します：

• 新しく作成したページを修正する
• 対応するページを修正する
• 範囲を明記して両方の内容を調整する
• または、実際には矛盾ではない（後述の軽微な不一致である）ことを確認する

矛盾が解決したら、ページからcontradiction-check行を削除します。 編集したページにcontradiction-check: failedの行が一つも残っていない場合に限り、作業を続けます。

2. 軽微な不一致 — 真の矛盾ではない食い違い：強調点の違い、妥当なバージョン差や測定誤差の範囲内の値、または異なる範囲で成り立つ主張などです。どのページにも何も書き込まず、作業も止めないでください。ユーザーが必要に応じて対応できるよう、ステップ11の要約に記載します。定期的なwiki-lintの一括チェックがその補完となります。

8. wiki/index.mdを再生成する

インデックスを手動で編集しないでください。この取り込みで作成した各ページには、すでにフロントマターにcategory、summary、createdが含まれています。これらがインデックスの正となる情報です。次のコマンドで再生成します：

python bin/generate-index.py

新しいソース、エンティティ、概念の各ページは、カテゴリの下に自動的に表示されます。フロントマターがないページについてジェネレーターが警告を出した場合、またはページがUncategorizedに分類された場合は、そのページのフロントマターを修正して再実行してください。

9. wiki/overview.mdを更新する

現在の概要を読み直します。このソースが以下に該当する場合：

• 重要な概念を導入する：「Key Entities / Concepts」に追加します
• 全体的な理解を変える：「Current Understanding」を更新します
• 新たな疑問を生む：「Open Questions」に追加します

フロントマターのupdated日付を更新します。

10. 操作を記録する

**先に必須確認を行います：**ステップ7bで、この取り込み中に編集したページにcontradiction-check: failedの行が残っている場合は、コミットを提案しないでください。ブロッキング矛盾を解決してから行を削除してください。コミットするページは、常に問題のない状態にします。

SCHEMAの操作ログとコミットの規約に従います：

• **Git Wiki：**Wikiの変更をステージし、コミットを提案します（件名はリポジトリの規約に従います。取り込みの場合のデフォルトはConventional Commitsのdocs:で、さらにトレーラーを付けます）。 ユーザーの確認を受けてからコミットしてください。自動でコミットしてはいけません。

  docs: summarize <source title>
  
  Wiki-Op: ingest
  

• 非Git Wiki：wiki/log.mdに追記します：

  ## [<today>] ingest | <source title>
  Pages written: <slug>
  Pages updated: <comma-separated list>
  

よくある間違い

• 編集せずに時系列の更新を追記する — Wiki ページは更新され続けるドキュメントであり、日記ではありません。## April 27 update: や **Update:** のような見出しの後に新しい内容を追加しないでください。該当するセクションをその場で更新し、frontmatter の updated 日付を更新して、変更内容を操作ログ（git wiki の場合はコミット、それ以外の場合は log.md）に記録してください。ログは履歴の記録であり、ページには現在の情報を記載します。
• バックリンクの監査（ステップ 7）を省略する — Wiki の価値は双方向リンクによって高まります。必ず既存のページを調べ、この情報源で新たに登場したエンティティがないか確認してください。
• [[slug]] リンクをでっち上げる — 存在を確認していない、または今作成していない slug への相互参照は絶対に記述しないでください。リンク先が存在しないリンクは、幻覚によるリンクです。既存のページ一覧（ls wiki/pages/）で確認してください。SCHEMA.md の Concept Identity ルールも参照してください。
• 要約を統合するのではなく、abstract を要約する — Summary セクションには、abstract を言い換えたものではなく、独自に統合した内容を記載してください。

11. ユーザーに報告する

• Summary ページ：wiki/pages/<slug>.md
• 作成または更新したエンティティ／概念ページ：
• バックリンクを追加したページ：
• インデックスと概要を更新済み
• 留意した軽微な相違点（ステップ 7b）：<list any non-blocking tensions, or "none"> — どのページにも記録していません。必要に応じて対応してください