jackin-research

jackin-research

オープンな疑問やロードマップのトピックについて、独立した調査資料を作成します。jackin❯ のドキュメントサイトで公開する複数ページの成果物です。ブリーフ主導で、まずブリーフを作成し、その後に調査を実行します。証拠（ウェブ＋コードベース）を収集して統合しますが、製品設計の決定は行いません。

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

使用する場合

• 担当者が、相応の規模の調査に対して jackin-research <slug> を実行する場合。

使用しない場合

• ロードマップ項目の設計判断 → jackin-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> を介して行います。