consolidate-notes

統合 — リサーチを正式な記事に昇格する

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

トピックに関する既存のリサーチを、articles/ 配下の正式な記事に昇格します。暫定ではなく正式なものです。出力は不確実性の記録ではなく、今後のエージェントにとっての信頼できる情報源です。

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

レガシー形式の読み取り： 既存のリサーチや記事では、status: provisional / canonical が使われている場合があり、既存の sources: に文字列のパスが含まれている場合もあります。これらはそれぞれ、ドラフト／安定版およびソースリソースとして扱ってください。一括で書き換えないでください。新たに書き込む場合は、以下の OKF 形式を使用してください。

停止ゲート：本当に決定されていますか？

統合は新規作成ではなく、昇格です。チームがまだ決定していない場合、作成された「正式な」記事はチームの理解状況を偽ることになります。今後のエージェントはそれを読み、行動し、その誤った確信が積み重なっていきます。

書き込みを行う前に、ユーザーに次の点を声に出して確認してください。

• 実際の決定は何ですか？（例：「CRDT には Yjs を選びました」。「Yjs は選択肢のひとつです」ではありません）
• どの代替案を検討し、却下しましたか？（これらは「検討した代替案」に記載し、同等の選択肢として扱わないでください）
• チームが用いた根拠は何ですか？（ソースからあなたが推測したものではありません）

決定がまだ保留中であれば、統合しないでください。ユーザーに「リサーチはまだ暫定的です。チームで決定したら、その結果を携えて再度統合してください」と伝えてください。その後、作業を停止します。

この手順を使う場合

• リサーチを経てチームが決定し、その結果を正式なナレッジとして確定したい場合
• 複数の暫定的なリサーチメモを、権威あるひとつの記事にまとめたい場合
• 開発者から、あるトピックのナレッジを「統合」または「最終確定」するよう依頼された場合

次の場合は統合しないでください。

• チームが実際には決定していない（出力が誤解を招くため、リサーチとして残してください）
• 元となるソースを読んでいない（出力の根拠が不足するため）

原則：暫定ではなく正式なもの

統合された記事は信頼できる情報源です。この記事を読むエージェントが背景を知るためにさらに調べる必要がないよう、記事単体で内容が完結していなければなりません。そのため、次の点を守ってください。

• 明確で直接的な記述にする（「暫定的」「初期調査結果」などは使わない）
• 決定事項は選択肢ではなく、決定事項として記述する
• 今後の読者が理由を理解できるよう、根拠を説明する
• トレードオフを認めつつ、選択肢の一覧ではなく、選んだ方針との比較として示す
• 根拠へのリンクを含めるが、記事全体をリンク集にしない。この記事が到達点であり、道筋ではありません

手順

1. リサーチとソースを読み込む

このトピックに関するリサーチ記事を探します。

• exec("grep -rn <topic-keyword> <content-dir>") を使って過去のリサーチを探すか、プロジェクト内の既知の場所にリサーチがまとめられている場合は exec("ls -A research") を使います
• 各リサーチ記事を exec("cat <path>") で最後まで読みます（リッチエンリッチメントにより、フロントマター、シャドーリポジトリのアクティビティ、プロジェクトの Git 履歴、バックリンクが提供されます）
• sources: フロントマターの一覧をたどり、参照されているソースファイルをすべて読みます
• このトピックに関する既存の正式な記事も読みます。すでに記事がある場合は、新規作成ではなく更新してもかまいません

統合するリサーチがない場合は、停止してください。統合は新規作成ではなく、昇格です。先に /research-with-sources スキルを実行してください。

2. 決定事項を再確認する

決定事項は、冒頭の停止ゲートですでに確認済みです。この手順では、手順 1 でリサーチを読み込んだ後に簡単な再確認を行います。読み込んだリサーチによって、ユーザーが当初説明したほど「決定」が確定していないと判明することがあります（反論されていない未解決の質問がある、またはユーザーが別の代替案を見落としていたなど）。その場合は一時停止し、書き込む前にユーザーに再確認してください。

3. 正式記事を作成する

作業を進めながら必ず保存してください。 複数の調査ドキュメントをまとめる大規模な統合作業では、まず記事の骨組み（フロントマターと以下の見出し）を作成し、各セクションが完成したらその都度 edit してください。合成した内容全体をコンテキストに保持して、最後に一度で書き込むことは避けてください。作業の途中でレート制限やクラッシュが発生しても、失われるのは記事全体ではなく一つのセクションだけです。（プラットフォームスキルの「Writing」セクションでは、長時間にわたるすべての作業にこのルールを適用しています。ナレッジベースがチェックポイントになります。）

コンテンツディレクトリ内に保存してください。パスの規則はプロジェクトによって異なります。

• プロジェクトが3層のライフサイクル（external-sources/ → research/ → articles/）を採用している場合は、articles/ に保存し、対象領域が広い場合はトピックごとのサブフォルダーに分類してください（例：articles/editor/crdt-architecture.md）。
• プロジェクトに既存の正式ドキュメント用レイアウト（docs/、guides/ など）がある場合は、プロジェクトの規則に沿った場所に保存してください。
• 正式な保存場所が不明確な場合は、ユーザーに確認してください。

フロントマター：

---
title: Descriptive title
description: One-line summary of what this article covers
type: article
status: stable
date: YYYY-MM-DD
tags:
  - article
  - canonical
  - topic-tag
supersedes:
  - <path-to-research-article>.md
---

構成：

## Summary

[One paragraph: what the decision is and why. A reader who reads only this paragraph should know the outcome.]

## Context

[What problem does this solve? What constraints shaped the decision?]

## Decision

[The chosen approach, stated directly. Not "we recommend" — "we chose".]

## Rationale

[Why this path over alternatives. Grounded in the constraints from Context.]

## Trade-offs

[What we gave up by choosing this path. Frame against the chosen decision, not as a menu.]

## Alternatives considered

[Briefly: what else was on the table, why it was rejected. Link to the research article for deeper analysis.]

## Implementation notes

[How this gets realized in the codebase — key files, patterns, gotchas.]

## Further reading

[Links to research articles and external sources for readers who want the trail.]

4. 積極的にリンクする

正式記事は参照先となるページです。関連するあらゆる場所から積極的にリンクし、記事自体からも関連するすべてのページへリンクしてください。正式記事へのリンクが不足すると、その価値の大部分が失われます。

• この記事内： 別のドキュメント（他の正式記事、関連する調査、外部ソースのページ、関連トピック）を指す名詞句はすべて、通常の文章として記述するのではなく、標準的なMarkdownリンクにしてください。
• すべてのリンクが有効でなければなりません。 実在するドキュメントにのみリンクしてください。独立したページを作るべき概念に言及する場合でも、そのページがまだ存在しないなら、壊れたリンクを出力しないでください。この作業でページを作成するか、追跡タスクとして記録してください（ホストにタスクツールがない場合は、ユーザーに伝えてください）。壊れたリンクは負債であり、ToDoの目印ではありません。
• 関連ページを更新します。 執筆後、exec("grep -rn <topic> <content-dir>") を使って、関連性の高い既存ページを2～3件探し、それぞれから新しい記事へのリンクを追加してください。通常は「関連項目」セクションか、新しい記事が関係する箇所にインラインで追加します。これにより、パスを覚えていなくてもバックリンクから記事を見つけられるようになります。
• 「Further reading」からソースと置き換えられた調査記事へリンクしてください。 その経緯をたどりたい読者が参照できます。

5. 調査記事を置き換える

新しい記事のフロントマターに、統合対象の調査記事を指す supersedes: リストを追加してください。これにより監査証跡が作成されます。

調査記事は削除しないでください。判断に至った経緯を示す歴史的な背景資料として残します。フロントマターを編集して、以下を追加してください。

status: deprecated
superseded_by: <path-to-new-canonical-article>.md

6. 検証する

• ファイルがコンテンツディレクトリ内の選択したパスに存在する
• フロントマターに type: article と status: stable がある
• 置き換える調査記事が列挙されている
• 調査記事が status: deprecated に更新され、superseded_by の参照先がある
• exec("ls -A <target-dir>") に新しいファイルが表示される

対象外

• まだ結論に至っていない調査を統合しないでください。 そうすると、チームの実際の理解状況を記事が誤って伝えることになります。
• 調査記事を削除しないでください。 経緯を示す資料です。superseded_by マーカーを付けて残してください。
• 調査の文章をそのまま書き直さないでください。 正式記事は直接的で結論が明確な文体、調査記事は探索的で暫定的な文体であり、両者は異なります。
• supersedes / superseded_by のリンクを省略しないでください。 監査証跡は、将来の読者にとって重要です。