Mjun Research

---
name: mjun-research
description: >-
  意思決定に必要な外部事実を一次資料 (公式ドキュメント・ソースコード・仕様書) から調査し、主張ごとに出典を付けて記録するSkill。
  ユーザーが「一次資料で調べて」「公式ドキュメントを確認して」と依頼したときや、spec作成中に外部仕様の知識不足でdecisionが決められないときに使うこと。
  会話済み内容のまとめや、対象リポジトリのコードを読むだけで足りる調査には使わない。
allowed-tools: Read, Write, Glob, Grep, WebSearch, WebFetch, Bash(git:*), Bash(mkdir:*), Bash(ls:*), Bash(cat:*)
---

# mjun-research

外部事実の知識不足をユーザーへの質問で埋めず、一次資料への調査で解決するSkill。調査結果はdecisionの証拠として呼び出し元へ返す。decisionそのものは確定しない。

## Arguments

- `question` (必須): 調査する質問。1回の起動で1つの質問だけを扱う
- `destination` (任意): 結果の保存先となる `.mjun/specs/<slug>` のLocal specディレクトリ。未指定で、会話の文脈からも特定できない場合は保存先をユーザーに確認する

## 調査の原則

- **出典を信頼度で階層化する**: 出典は次の3階層で扱う
  - Tier 1: 標準仕様、対象ライブラリのソースコード、公式ドキュメント・first-partyのAPIリファレンス
  - Tier 2 (first-party artifacts): changelog / release notes、issue trackerのmaintainer発言、テストコード、git履歴
  - Tier 3 (secondary): 解説記事、第三者ベンチマーク、Q&Aサイト、コミュニティの報告
- **Tier 1/2を優先する**: Tier 1/2で確認できる主張は、Tier 3を根拠にしない。Tier 3は資料の所在探しの手がかりとして使う
- **Tier 3は経験的な主張に限って根拠にする**: 運用上の問題、メンテナンス状況、実測性能など、Tier 1/2に記述が存在しない主張に限り、Tier 3を根拠として記録する。`Source` にTier 3であることと、参照した件数・報告の一致度を明記し、「未確認」とは区別する
- **undocumented behaviorを区別する**: ソースコードで確認できるがドキュメントに記述のない挙動は、主張に `undocumented` と印を付ける。将来のバージョンで変わりうる事実として呼び出し元が扱えるようにする
- **バージョンを特定する**: 対象リポジトリが使っているバージョン (lockfile、manifest) を確認し、そのバージョンに対応する資料を読む
- **事前知識は仮説に留める**: 事前知識は確認の優先順位を決めるためだけに使い、根拠にしない。事前知識が古い可能性を前提に、確信が持てない点・変わっていそうな点から先にTier 1/2で確認する
- **主張ごとに出典を付ける**: 調査結果の各主張に、URL・ファイルパス・仕様の節番号など、検証可能な出典を添える。出典には参照日、またはドキュメントのバージョン・ソースコードのcommit hashを併記する。出典を示せない主張は「未確認」として区別する
- **矛盾を明示する**: 公式ドキュメントとソースコードの挙動が食い違う、バージョン間で仕様が異なる、といった場合はどちらかに寄せず、両方の主張を出典付きでFindingsに書く
- **decisionを確定しない**: 調査は判断材料の提供までとする。結果を受けたdecisionの分類・決定は呼び出し元が行う

## 手順

1. 質問を、答えの形が定まる1文に明確化する。複数の質問が混ざっている場合は分割し、今回の1問を呼び出し元またはユーザーに確認する
2. 事前知識から答えの仮説を立て、確認すべき事実を列挙する。確信が持てない点・古くなっていそうな点を先頭に置く
3. 対象リポジトリの依存とバージョンを確認し、読むべきTier 1/2の資料を特定する
4. 資料を調査する。WebSearchは資料の所在探しに使い、英語と日本語の両方で検索する。根拠はTier 1/2の本体から取り、Tier 3は経験的な主張に限って根拠にする
5. 記録する前に次を点検し、欠けがあれば手順4に戻る
   - 手順1の質問に答えきれているか。手順2で列挙した事実に未確認のものが残っていないか
   - 結論を覆しうる直近の変更 (release notes、deprecation、破壊的変更) を見落としていないか
   - 主要な主張に対して、Tier 1/2の中に反例や矛盾する記述がないか
6. 結果を次の形式で記録する

```markdown
# Research: <topic>

## Question

<調査した質問>

## Findings

- <主張 1>
  - Source: <URL / path / 仕様の節> (<参照日 または version / commit hash>)
- <主張 2> (undocumented)
  - Source: <ソースコードのpath> (<commit hash>)
- <経験的な主張>
  - Source: Tier 3。<URL 1>、<URL 2> (<参照日>)。<件数>件中<件数>件が一致
- <資料間で食い違う主張>
  - Doc: <ドキュメントの主張> — Source: ...
  - Code: <ソースコードの挙動> — Source: ...

## Unresolved

- <どの階層の出典でも確認できなかった点。なければ「なし」>

## Implication

<このdecisionに対して調査結果が示唆すること (推奨ではなく含意)>
```

7. 保存する
   - 既定: `.mjun/specs/<slug>/research/<topic>.md` (`<topic>` は内容を表す英語kebab-case。`research/` が無ければ作成する)
   - specに紐づかない単発調査: 保存先をユーザーに確認してから保存する
8. 呼び出し元へFindings・Unresolved・Implicationを返す。調査結果をGitHub Issueへ投稿しない。外部への投影が必要な場合は、contract承認後の呼び出し元が担う