research

research

未解決の課題やロードマップのトピックについて、jackin' のドキュメントサイトで公開する複数ページの調査資料を作成します。まずブリーフを作成してから、調査を実行します。証拠（ウェブとコードベース）を収集して統合しますが、プロダクトの設計上の決定は行いません。

参考実装：jackin' リポジトリの docs/content/docs/research/token-optimization-research/。

使用する場合

• 運用担当者が /jackin-dev:research <slug> を実行して、本格的な調査を行う場合。

使用しない場合

• ロードマップ項目の設計上の決定 → /jackin-dev:brainstorm。
• 簡単な確認 → deep-research または Explore を直接使用し、調査資料は作成しません。

引数

• --brief-only — ブリーフである prompt.mdx を作成して終了します。後で /goal Follow <brief> を実行して調査します。
• --in-roadmap — 独立した調査資料ではなく、ロードマップ項目に調査結果を直接記載します（小規模な調査向け）。
• --web-only / --codebase-only — 情報収集をいずれか一方に限定します。

出力レイアウト（デフォルト：独立したフォルダー）

docs/content/docs/research/<slug>/
├── meta.json     # { title, defaultOpen:false, pages:[...] } — sidebar order
├── index.mdx     # dossier landing: headline numbers, how-to-read, tier list
├── prompt.mdx    # the brief that was run (the spec; carries the /goal run line)
├── NN-*.mdx      # numbered chapters (00 summary, 01.. foundations, 10-20 areas, 30+ synthesis)
└── tools/        # optional scripts + own meta.json + index.mdx

親の docs/content/docs/research/meta.json の pages にも <slug> を追加します。大規模な調査は独立したフォルダー（デフォルト）に、小規模な調査は --in-roadmap に記載します。

プロセス

1. スコープ設定／ブリーフ作成。 トピック（またはロードマップ項目）をもとに、prompt.mdx を作成するか、既存のものを読み込みます。ミッション、章の一覧、証拠のルールを定めます。--brief-only を指定した場合は、ここで終了します。
2. 情報収集。 ウェブは組み込みの deep-research を、コードベースは Explore／grep を使用します。外部の主張にはすべて出典 URL を付け、ローカルの数値にはすべて算出方法を記載します。
3. 執筆。 index.mdx（主要な数値、読み方、評価リスト）と、固定の手法別レコードスキーマに沿った番号付きの章を作成します。再現用スクリプトがあれば tools/ にまとめます。
4. サイドバーの設定。 調査資料の meta.json と親の research/meta.json を作成または更新します。
5. ドキュメントのチェックとコミット。 docs/ から bun のドキュメントチェック（build、check:repo-links、tsc --noEmit、test）を実行します。docs(research): でコミットし、プッシュします。

よくある間違い

• Problem／Why／Design の形式を無理に当てはめる — 調査資料の形式は自由であり、ロードマップ項目ではありません。
• 設計上の決定を行う — それは brainstorm の役割です。
• 出典のない外部の主張や、算出方法が記載されていないローカルの数値。
• meta.json の pages とディスク上のファイルが一致していない。

ツール

cargo xtask research scaffold <slug> はフォルダーと meta.json を作成します。cargo xtask research check は pages とディスク上のファイルが一致しているか検証します。通常、調査の実行には外部の /goal Follow <brief> を使用します。