research-with-sources

調査 — 情報源を集め、暫定的な調査結果をまとめる

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

トピックについて証拠に基づく調査を行い、暫定的な調査記事を research/ に作成します。正式なものではなく、暫定版です。調査記事には、その時点での調査結果、トレードオフ、未解決の疑問点を記録します。決定事項が固まった場合に限り、/consolidate-notes スキルを通じて正式な記事に昇格させます。

コンテンツディレクトリは、解決済みの content.dir です。まだ把握していない場合は、config({ key: 'content.dir' }) で読み取ってください。以下のパスは、このディレクトリを基準とした相対パスです。

3 つのパス

• パス A — 調査記事（デフォルト）： status: draft を設定し、取り込み手順で取得した生の情報源を参照するインラインの sources: フロントマターリストを含む、継続的に参照できる暫定記事です。ユーザーが明示的にオプトアウトしない限り、これがデフォルトです。
• パス B — 直接回答： 調査結果を会話内だけで伝えます。ユーザーからの明示的な依頼が必要です（例：「答えだけ教えて」「ドキュメントは不要」「手短に回答して」）。
• パス C — 既存の調査記事を更新： 既存の調査記事に対して、必要な箇所のみ追加・修正します。ユーザーが既存の調査ドキュメントに言及した場合、または「更新／最新情報に更新／拡張して」と依頼した場合に該当します。

パス A がデフォルトなのは、暫定記事は時間とともに蓄積される一方、口頭の回答は蓄積されないためです。

レガシー記事の読み取り： 既存の記事では、status: provisional や sources: の文字列パスが使われていることがあります。これらはドラフトの調査記事およびソースリソースとして扱ってください。まとめて書き換えないでください。新規作成では、以下の OKF 形式を使用します。

自律実行モード

モード	動作	開始条件
監督あり（デフォルト）	ユーザーに基準の確認を求めるスコープ設定のゲートで停止します。対象範囲の決定は、対話形式で進めます。	ユーザーがセッションを進行する場合のデフォルトです。
ヘッドレス	提案した基準を自動で確定します。ルーティングの決定も自動で選択します。対話型プロンプトは省略します。その他のすべてのゲート（スキャン、分析、検証、根拠付け）は引き続き適用されます。	「待たずに進めて」「そのまま進めて」「ヘッドレスで実行して」という明示的な指示、または非対話型のコンテナ環境。

ヘッドレスモードでは、基準を提案したら直ちに作業を進めてください。提案後、スコープ設定タスクを完了としてマークします。

---

必須の実行順序

必須ゲート — 先に進んで省略してはいけません。 ステップ 0〜2 を完了せずに WebFetch または WebSearch を実行しようとしている場合は、停止してください。ゲートを省略しています。

1. ステップ 0：ワークフローのチェックポイントタスクを作成する — 必ず最初に行います。
2. ステップ 1：既存の対象範囲をスキャンしてルートを決める — コンテンツディレクトリをスキャンして既存の作業を確認し、対象範囲を分類します。新しい調査を始める前に選択肢を提示します。
3. ステップ 2：共同でスコープを設定する — 調査の基準を提案します。監督ありモードでは、外部から取得する前に停止し、ユーザーの確認を待ちます。
4. ステップ 3：取り込みを通じて生の情報源を取得する — 分析する前に保存します。
5. ステップ 4：読み取って分析する — デフォルトではサードパーティ／外部情報を対象とします。ユーザーが明示的に依頼した場合に限り、ファーストパーティのコードベースを対象とします。
6. ステップ 5：調査記事を作成する — パス A のみ。
7. ステップ 6：積極的にリンクを付け、価値のある Q&A をファイルに反映する。
8. ステップ 7：検証する — フロントマター、リンク切れ、情報源との整合性。
9. ステップ 8：要約し、次の進め方を提案する。

パス B のショートカット： ステップ 2 でユーザーが直接回答を明示的に依頼した場合は、ステップ 5 と 7 を省略します。それでもステップ 0、1、3、4、6、8 は適用されます（会話で回答する場合でも、証拠を重視する規律は緩めません）。

---

レポートの基本方針：外部／サードパーティの情報源

調査記事では、外部を基本方針とします。サードパーティのトピック、テクノロジー、概念、公開リポジトリ、論文、公式ドキュメントを調査します。ユーザーから明示的に依頼されない限り、ユーザー自身のコードベースの分析を調査記事に混在させないでください。 混在させると、事実の統合から組織に対する意見形成へと内容がずれ、事実への忠実性が低下します。

• デフォルト： 外部情報源（ウェブ、オープンソースのリポジトリ、論文、公式 API）。
• 例外： ユーザーが「自分たちの X と Y を比較して調査して」や「自分たちのコードベースを含めて」と依頼した場合は、それを含めます。ただし、読者が外部から検証可能な事実と組織固有の見解を区別できるよう、記事では自組織の観察結果とサードパーティの調査結果を明確に分けてください。

---

進行に合わせて保存する — 記事自体がチェックポイントです

進行に合わせて保存する — クラッシュに備えたチェックポイントのルール。 この手順で最も大きな損失につながるのは、セッション中のレート制限やクラッシュによって、完了した調査が失われることです。コンテキスト内に保持された分析は一度も書き込まれないまま、セッション終了時に破棄されます。ユーザーが費やした作業が消えてしまいます。ナレッジベースをチェックポイントとして、次の2つのルールに従えば、すべての段階でクラッシュに備えられます。

• ソースを取得したら（Step 3）、その都度、1件ずつ取り込みます。 すべてのソースを取得してから最後にまとめて取り込むことは避けてください。取り込み済みのソースはクラッシュ後も残りますが、取得しただけで書き込まれていないソースは残りません。
• 記事の骨組みを早めに作成し、最後に一度だけ書き込むのではなく、読み進めながらセクションごとに埋めていきます（Steps 4-5）。 各ソースを分析したら、次のソースに進む前に、その結果を記事にeditで反映します。8件中5件を読んだ後にクラッシュしても、5つのセクションは KB に安全に残っています。調査を最初からやり直すのではなく、部分的な記事を読み返して続行できます。

コンテキスト内にしか存在しない構造化メモは、保存された作業ではありません。残す価値のある調査結果は、取り込み済みのソースか記事に書き込んでください。保持するだけでなく、書き込んでください。

---

Step 0: ワークフローのチェックポイントタスクを作成する

必ず最初に実行します。 読み取り、スキャン、取得を始める前に、タスクを作成してください。タスクはコンテキストの圧縮後も保持され、手順の抜けがすぐに分かり、進捗をユーザーに示せます。

ホストのタスクシステムを使って、次のタスクを作成します（Claude では TaskCreate、それ以外では同等の機能を使用します）。

TaskCreate: "Research: Scan existing coverage + route"        → start as in_progress
TaskCreate: "Research: Collaborative scoping — rubric gate"   → pending, blocked by #1
TaskCreate: "Research: Capture sources via ingest"            → pending, blocked by #2
TaskCreate: "Research: Read + analyze"                        → pending, blocked by #3
TaskCreate: "Research: Write the research article"            → pending, blocked by #4
TaskCreate: "Research: Link aggressively + file Q&A back"     → pending, blocked by #5
TaskCreate: "Research: Validate (frontmatter + dead-links)"   → pending, blocked by #6
TaskCreate: "Research: Recap + follow-up directions"          → pending, blocked by #7

ホストの依存関係機能を使って、タスクの実行順序を制御します。各ステップの完了時に、そのタスクを completed にし、次のタスクを in_progress にします。

Path B の場合： スコープの決定で Path B（直接回答）になった場合、該当しないタスク #5 と #7 を削除します。

Path C の場合： Step 1 で Path C（既存記事の更新）に進む場合、タスク #3 と #5 を削除します（通常、取り込みは不要で、新しい記事も作成しません）。また、タスク #4 の名前を「Research: Read existing article + diff deltas」に変更します。

タスクを作成する理由：確認されている失敗パターンは、エージェントがスキャンやスコープの確認をせず、いきなり WebFetch を実行することです。タスクがあれば、手順の抜けをセッション中にユーザーがすぐ確認できます。

---

Step 1: 既存の情報範囲をスキャンして進行先を決定する

必須の最初の調査ステップです。 外部情報を取得する前に、ナレッジベースにすでにある情報をスキャンしてください。

フェーズ 1：既存の知見を確認する

ユーザーが既存の調査記事を明示的に参照している場合（記事名を挙げる、リンクする、「更新／再確認／拡張」と述べる）： → スキャンをスキップします。Path C に直接進みます。

それ以外の場合は、必ず最初にスキャンします：

1. exec("grep -rln <topic-keyword> <content-dir>") — 関連するファイルを返します。フロントマターの情報も含まれるため、各ファイルを開かずに関連性を判断できます。
2. exec("ls -A <content-dir>") — フォルダー構成と、サブディレクトリーごとに最も最近更新されたドキュメントを確認できます。
3. 最も有望な候補の 1～3 件について、exec("cat <path>") を実行します — ドキュメント全文、フロントマター、バックリンク、シャドーリポジトリーの最近の動向が返されます。

分類：

カバレッジ	意味	進む先
完全にカバーされている	既存の記事が、根拠を示して質問に直接回答している	調査結果を提示し、詳しい説明、検証、拡張、または明確に新規レポートを作成することを提案します
一部カバーされている	関連する調査があり、具体的な質問は自然な拡張にあたる	次の選択肢を提示します：（1）Path C で既存の記事を拡張、（2）Path A で新しい記事を作成
カバーされていない	意味のある重複がない	Path A（既定）または Path B に進みます

フェーズ 2：進め方の選択肢を提示する（監督モード）

完全にカバーされている場合：

「<path> に、このテーマに関する調査があります。調査で分かったことは次のとおりです：[主な調査結果を 2～4 件]。選択肢：（1）そのまま使用、（2）検証／再確認（記事の日付：[date]）、（3）[具体的な側面]を拡張、（4）異なる切り口であれば新規に調査。」

ユーザーに選んでもらいます。既存の調査ですでに質問に回答できている場合、新たな調査を始めてはいけません。

一部カバーされている場合：

「<path> に、[対象範囲]を扱った関連調査があります。[topic]についての質問には直接回答していませんが、自然な拡張にあたります。選択肢：（1）Path C で既存の調査を拡張、（2）Path A で新しい記事を作成。理由は[理由]のため、[1 または 2]をおすすめします。」

カバーされていない場合：

ステップ 2（スコープの設定）に進みます。ユーザーが簡潔な回答を求めている場合は、Path B が適用される可能性を伝え、ステップ 2 のスコープ設定のやり取りで確認します。

ヘッドレスモード： 自動的に選択します。完全にカバーされている場合 → 呼び出し元が依頼した具体的な切り口で新しい記事を作成。一部カバーされている場合 → 新しい記事を開始。カバーされていない場合 → Path A。

スキャンの方針

• スキャンを省略しないでください。 grep と cat に 30 秒かけるだけでも、調査の重複を防ぎ、既知の情報をユーザーに伝えられます。
• 意味的に一貫性のあるテーマでは、既存記事の拡張（Path C）を優先します。重複する記事を 2 つ作るより、包括的な記事を 1 つ作るほうが適切です。
• 切り口、対象読者、または主な問いが大きく異なる場合は、新規作成（Path A）を優先します。

---

ステップ 2：協力してスコープを設定する（監督モードの STOP ゲート）

厳格なゲート（監督モード）。 ユーザーがルーブリックを承認するまで、外部調査を始めてはいけません。提案した後は、停止してユーザーの返答を待ってください。 その後に限り、スコープ設定タスクを完了としてマークします。

ヘッドレスモードの場合： ルーブリックを提案し、そのまま進めます。提案した後、タスクを完了としてマークします。

ルーブリックを提案する

次の構成をユーザーに返します：

## Proposed research rubric

**Question:** [narrowed from the original topic — concrete, answerable, bounded]

**Dimensions to investigate:** [3-7 facets]
1. [Dimension 1]
2. [Dimension 2]
...

**Candidate sources:** [3-8 initial guesses]
- [Source 1 — why it's relevant]
- [Source 2 — why it's relevant]
...

**Success criteria:** [2-3 concrete outcomes — "the article cites X authoritative sources", "open questions are marked explicitly", etc.]

**Output format:** Path A (article) | Path B (direct answer) | Path C (update `<existing-article>`)

スコープ設定の方針

• 元のテーマが曖昧な場合（「LLM エージェントを調査する」など）は、情報を取得する前に範囲を絞ります：「具体的にどのエージェントですか？ どのような意思決定のためですか？ どのくらいの期間を対象にしますか？」
• テーマが URL そのものである場合は、その URL を起点として扱い、関連する権威ある情報源を 2～4 件加えます。
• この調査に役立つ意思決定を明示します。意思決定の背景がない調査は、焦点が定まりません。
• ルーブリックを細かく指定しすぎないでください。ユーザーは調整できます。指示するのではなく、提案してください。

ステップ 3：取り込みで生のソースを保存する

確認済みの評価基準に含まれる関連 URL、論文、または文書ごとに、取り込み手順に従ってください。この手順はこのパック内ではなく、プラットフォームの /open-knowledge スキルにある references/ingest-and-sources.md に記載されています。**通常、調査で取り込むソースは 3〜8 件です。**少なすぎると、統合内容が薄くなります。多すぎると、セッションの残りを読むことに費やすことになります。

• **取り込みを省略しないでください。**生の情報を保持すれば、取得と解釈を切り分けられ、調査の再現性も高まります。ソースが保存されていない記事は単なる意見ですが、ソースが保存されている記事なら、ほかの人もたどれる道筋になります。
• 特に必要なソースの取得に失敗した場合は、処理を止めてユーザーに貼り付けを依頼してください。黙って除外してはいけません。執筆時に証拠の欠落を捏造で埋めることが、最大の失敗要因です。
• 取得結果が生データではなく明らかな要約（LLM ベースの取得ツールにはそのようなものもあります）だった場合は、その旨を記録し、生データを取得できる代替手段（curl -sL <url>、またはユーザーに貼り付けを依頼する）を試してください。

---

ステップ 4：読む＋分析する

取り込んだ各ソースを注意深く読んでください。あわせて、次のものも読み込みます。

• トピックに関する既存の正規記事 — exec("cat <path>")（フロントマター＋バックリンク＋シャドーリポジトリのアクティビティを返します）。
• 関連トピックに関する過去の調査 — OpenKnowledge の Markdown ファイルを対象に、同様に exec("cat <path>") を実行します。
• 関連するソースコード — ユーザーが一次情報源に基づく分析を求めた場合のみ。.ts／.js などにはネイティブの Read を使い、対象範囲内の .md／.mdx には exec を使います。
• プロジェクトのコンテキスト — プロジェクトが設計資料を保存している場所を確認します。

構造化したメモを取ります。

• 重要な主張とその根拠 — すべての主張に、参照先となるソースが必要です
• 選択肢間のトレードオフ
• ソース間の矛盾 — これは記事の中で最も価値のある部分になることがよくあります
• 不明点と未解決の疑問 — わかっていることの範囲
• 目の前の具体的な判断との関連性

**メモは後からではなく、取りながら記事に書き込んでください（必須 — 上記の随時保存するを参照）。**読み始める前に、フロントマターとステップ 5 のセクション見出しを含む記事の骨組みを作成し、各ソースの分析を終えたらすぐに、その結果を該当セクションへ edit で反映します。「メモ」は進行中の「調査結果」セクションそのものです。ステップ 5 で一度に書き起こすために、メモをコンテキスト内にため込まないでください。ここからステップ 5 までの間にレート制限が発生しても、すでに行った分析が失われないようにしてください。ステップ 5 に到達する頃には、記事の大部分が書き上がっている状態にし、ステップ 5 は仕上げと推敲の段階にします。

根拠に基づく記述の徹底

記事中の事実に関する主張には、すべてインラインで出典を引用する必要があります。出典のない推測は避けてください。根拠がない場合は、（a）追加で検索して出典を引用する、（b）インラインで (TODO: needs source) と記す、または（c）その主張を書かない、のいずれかにしてください。決して捏造しないでください。

---

ステップ 5：調査記事を書く（パス A のみ）

進めながら記録するを実行した場合、記事はすでに存在し、ステップ 4 の内容がかなり記入されています。このステップでは、白紙から書くのではなく、記事を仕上げます（残りのセクションを記入し、推奨事項を明確にし、以下の構成と検証のチェックを実行します）。記事が存在しない、または内容が薄く、中断後に作業を再開する場合：まず exec("cat <path>") で未完成の記事を読み込み、不足しているセクションだけを記入してください。また、ステップ 4 の分析のうち、KB に一度も書き込まれなかった内容はセッション中断時に失われているため、実際に不足している内容だけを再導出してください。ここで文書をゼロから作成するのは、段階的に進めるルールに従わなかったということであり、望ましい進め方ではなく、失敗パターンです。

コンテンツディレクトリ内に Markdown 文書を保存します。パスの規則：

• プロジェクトが 3 層のライフサイクル（external-sources/ → research/ → articles/）を採用している場合は、research/<slug>.md に保存します。
• プロジェクトに既存の docs/reports/specs のレイアウトがある場合は、それに合わせます。
• 大きなトピックにはサブフォルダを使用します：research/<topic>/<subtopic>.md。

ファイル名：内容がわかる kebab-case の名前にします（crdt-alternatives-for-editor.md、llm-wikis-and-knowledge-bases.md）。日付は含めません。日付はフロントマターに記載します。

フロントマター

---
title: Descriptive title
description: One-line summary of the research question
type: research-note
status: draft
date: YYYY-MM-DD
tags:
  - research
  - provisional
  - <topic-tag>
sources:
  - resource: ../external-sources/<source-1>.md
  - resource: ../external-sources/<source-2>.md
---

構成

## Question

[What specific question does this research answer? Be precise.]

## Context

[Why does this matter? What decision does it inform? Who is the reader?]

## Findings

[Main findings organized by theme, option, or criterion. Every claim cites a source inline.]

### Theme / Option 1

- Pros — with evidence links
- Cons — with evidence links
- Evidence: [Source A](../external-sources/source-a.md), [Source B](../external-sources/source-b.md)

### Theme / Option 2

...

## Trade-offs

[What you gain vs. lose with each option. A comparison table often helps.]

## Open questions

[What you still don't know — candidates for further research, prototyping, or human-judgment decisions.]

## Tentative recommendation

[Your best guess, clearly marked as tentative. Explain the reasoning so a future reader can re-evaluate when new information arrives.]

## Further reading

[Links to the ingested sources + adjacent research + any canonical articles on the topic.]

文体

• 確定事項ではなく、暫定的な内容にします。「暫定的な」「初期調査の結果」「現時点での理解に基づく」といった表現を使います。
• 確定事項であるかのように書かないでください。誤解を招きます。確定事項としてまとめるのは、決定が下された後の /consolidate-notes スキルの役割です。
• **不確実性を明示します。**調査は、不確実性を残しておくためのレイヤーです。

---

ステップ 6：積極的にリンクし、価値のある Q&A をファイルに保存する

調査記事は、新しい情報を見つけるための入り口です。リンクが不十分な調査は、誰にも見つけられない孤立したページになってしまいます。

リンクのルール

• 別の文書を指す名詞句はすべてリンクにします。標準的な Markdown を使います：[text](./relative/path.md)。
• 出典はフロントマターの sources: リストに記載するだけでなく、引用する箇所にインラインでリンクします。According to [LLM Agents](../external-sources/llm-agents.md)... のほうが、sources: に出典を記載するだけより効果的です。
• 関連する調査記事同士を相互リンクします。隣接するトピックに独自の調査文書がある場合は、「未解決の質問」セクションに記載するか、本文中でリンクします。あるテーマを追っている読者が、関連するほかのテーマも見つけられるようにします。
• 書き終えたら、関連性の高い既存ページを 1～2 件更新し、この調査記事へのリンクを追加します（通常は「関連資料」または「こちらも参照」セクションに記載します）。これにより、バックリンクを通じて調査記事が見つかりやすくなります。
• リンクをバッククォートで囲まないでください。また、HTML アンカーも使用しないでください。プラットフォームスキルのリンクルールに従ってください。

価値のある Q&A をファイルに保存する

調査セッション中にユーザーから具体的な質問があり、出典を示せる回答が得られた場合は、チャットだけに残さず、調査記事と同じ場所に短い独立ページとして保存します。出典に基づく回答がある具体的な質問は、作成できるナレッジの中で最も有用性の高い単位です。

• 短いファイル名にします：what-does-X-mean.md、how-does-Y-work.md
• 同じオブジェクト形式の sources: フロントマターを含めます
• この調査文書の「関連資料」から回答ページにリンクします
• 独立したファイルにするほどではない短い回答はチャットに残し、細分化しすぎないでください

---

ステップ 7：検証する

完了とする前に、次のチェックリストを実行します。

• コンテンツディレクトリ内の選択したパスにファイルが存在する
• フロントマターに title、description、type: research-note、status: draft、date、オブジェクト形式の sources: リストがある
• exec("ls -A <dir>") で、新しいファイルとフロントマターの内容が表示される
• audit({ path: "<doc-path>.md" }) の結果に問題がない（リンター違反と内部リンク切れがすべて検出される）。指摘された内容をすべて修正する
• Findings の各事実について、出典へのインライン引用がある
• ステップ 3 でリンクしたすべての出典ファイルが存在する（出典リンク切れがある場合、どこかで取り込みに失敗している）
• ステップ 6 の「書き終えたら、関連性の高い既存ページを更新する」というルールに従い、少なくとも 1～2 件の関連文書からこの調査記事にリンクしている

ステップ 8：まとめと今後の調査の方向性

会話の中で、ユーザーとのやり取りを締めくくります。

## Recap

- [Finding 1 — with source]
- [Finding 2 — with source]
- [Key trade-off / contradiction surfaced]
- [1-2 open questions that remain]

**Tentative recommendation:** [state it in one sentence]

**Follow-up research directions** (Path A candidates for later):
1. [Direction 1 — what would it investigate?]
2. [Direction 2 — what would it investigate?]
3. [Direction 3 — what would it investigate?]

今後の調査の方向性は、外部ソースの調査にしてください。ユーザーのコードベースに対する作業は含めません（それらは追加の調査ではなく、仕様書に記載する内容です）。それぞれの方向性は、後から単独で調査できるトピックにしてください。

ヘッドレスモードでは、対話形式で尋ねる代わりに、調査記事の「Further reading」セクションにまとめを記載します。

---

対象外

• 正式な記事として確定しないでください。 実際に決定が下された後に、/consolidate-notes スキルを使って正式な記事にするのが役割です。早まって正式な記事にすると、不確実性が埋もれ、後から読む人に誤解を与えます。
• 不確実性を隠さないでください。 「まだわかっていない」と書いてもよいのが調査の段階です。その旨を明確に伝えてください。
• 取り込みを省略しないでください。 常にまず元のソースを取り込み、その後に分析してください。ソースが保存されていない記事は、意見にすぎません。
• ステップ 1 のスキャンを省略しないでください。 調査の重複はユーザーの時間を無駄にするだけでなく、既存の調査を発展させる機会も逃します。
• 監督モードでは、スコープ確認のゲートを省略しないでください。 ユーザーの評価基準は、その後のすべての作業を左右します。スコープを誤った記事を、後から低コストで修正することはできません。
• 依頼がない限り、第一者のコードベース分析を記事に混在させないでください。 そうすると、調査結果は事実に基づく統合から意見へと逸れていきます。
• 既存の調査を黙って上書きしないでください。 そのトピックが以前に調査されている場合は、反復調査（パス C）を行うか、crdt-alternatives-2.md のように明確な名前を付けた後継記事を作成し、以前の記事が置き換えられたことを示してください。