itarunnn/jp-lit-mcp / skills/jp-lit-research
jp-lit-research
Verified日本語人文社会系文献調査スキル。jp-lit MCP サーバーを使って NDL・CiNii・J-STAGE・IRDB・JDCat・NIHU Bridge・国会会議録などを横断検索し、 書誌確認・所蔵調査・テーマ文献探索・古語表記ゆれ検索・デジコレ全文OCR・図版検索を行う。 「文献DBで調べて」「文献DBを始めます」など、文献DB という起動語を明示した文献調査依頼で使用する。 一度発火したらセッション中は継続して調査を進める。 SKIP: 「調べて」単体・API ドキュメント調査・Web 検索・一般的な質問への説明。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 19.6 KB |
| heuristics/advisory-consultation.md | markdown | 8.7 KB |
| heuristics/clarifying-questions.md | markdown | 3.5 KB |
| heuristics/db-characteristics.md | markdown | 7.2 KB |
| heuristics/evidence-grading.md | markdown | 7.9 KB |
| heuristics/failure-modes.md | markdown | 13.7 KB |
| heuristics/query-expansion.md | markdown | 4.6 KB |
| heuristics/source-selection.md | markdown | 20.0 KB |
| reference/01-core-workflow.md | markdown | 10.9 KB |
| reference/02-source-and-query.md | markdown | 14.8 KB |
| reference/03-evidence-and-output.md | markdown | 29.6 KB |
| reference/04-ephemeral-web-discovery.md | markdown | 4.0 KB |
| reference/regional-public-library-research.md | markdown | 11.7 KB |
| scripts/plan-regional-library-search.mjs | script | 16.0 KB |
| workflows/bibliography-lookup.md | markdown | 5.7 KB |
| workflows/field-orientation.md | markdown | 8.3 KB |
| workflows/fulltext-page-lookup.md | markdown | 16.0 KB |
| workflows/historical-term-search.md | markdown | 4.8 KB |
| workflows/image-illustration-search.md | markdown | 3.9 KB |
| workflows/research-guide-lookup.md | markdown | 8.7 KB |
| workflows/topic-literature-review.md | markdown | 8.1 KB |
reference/03-evidence-and-output.md
View on GitHub# jp-lit-research evidence and output
## 候補確度と本文確認
結果は `候補確度`、`確認`、`本文` を分けて報告する。単独の `確認済み` は使わない。
候補確度ラベル:
- `候補確度: 書誌確認済み`: 題名・著者・発行年・永続 ID などが信頼できる DB で確認できた。本文読了は意味しない
- `候補確度: 有力候補`: 書誌や OCR ヒットはあるが、同名別資料や OCR 誤認識などの確認が残る
- `候補確度: 弱い候補`: タイトル類似、関連語ヒット、二次情報のみなどで追加確認が必要
- `候補確度: 関連性未確定`: 検索結果には出たが、本文・要旨・目次のいずれでも関連性を確認していない
検索ヒットのみの場合は `確認: 検索ヒットのみ` とし、`候補確度: 関連性未確定` または `優先: 保留` を併記する。OCR ヒットのみで本文内容を断定しない。
## 仮整理・根拠・確認優先度
本文未確認の文献でも、タイトル・要旨・目次・学術書評・専門誌書評・出版社紹介・Web 断片から仮整理してよい。ただし、本文読解に基づく要約・分類・位置づけのように見せない。報告では、必要に応じて次の短いラベルを使う。
| ラベル | 目的 |
| --- | --- |
| `仮整理` | 候補を探索上どう見ているか。本文未読でも根拠付きで使う |
| `優先` | 調査上の確認優先度。文献価値の確定ではない |
| `根拠` | 仮整理・優先度の材料。本文、要旨、目次、学術書評、専門誌書評、出版社紹介など |
| `確認` | エージェントがどこまで確認したか |
| `本文` | 本文への入口・アクセス可否・読了状態 |
| `次` | 次に人間またはエージェントが確認すべきこと |
`availability.online=true` や PDF / HTML / デジコレ / リポジトリへのリンクは、オンライン上に入口があることを示すだけで、エージェントが本文を読んだことを意味しない。本文または該当箇所を読んだ場合だけ `確認: 本文` / `本文: 確認済み` とする。
確認ラベル:
- `確認: 書誌`: DB で存在・基本書誌を確認。内容把握は未確認
- `確認: 要旨`: 要旨・抄録まで確認。内容把握は要旨の範囲
- `確認: 目次`: 目次・章題・初出一覧・版注記などを確認。本文論証は未確認
- `確認: 本文`: エージェントが本文または該当箇所を読んだ
- `確認: 引用経由`: 他文献・書評・Web 断片経由。本文確認の代替にはしない
- `確認: 検索ヒットのみ`: 検索結果には出たが、関連性は未確定。本文確認の代替にはしない
本文ラベル:
- `本文: 未確認`: 本文の有無・アクセス可否をまだ確認していない
- `本文: オンライン入口あり未読`: PDF / HTML / デジコレ / リポジトリ等への入口は見つかったが、エージェントは本文を読んでいない
- `本文: オンライン入口なし`: 今回確認した範囲では本文入口が見つからない
- `本文: アクセス制限`: 館内限定、図書館送信、契約 DB、ログイン、購読などが必要
- `本文: 確認済み`: エージェントが本文または該当箇所を読んだ
優先ラベル:
- `優先: 高`: 代表研究候補、一次資料、同時代証言、公的資料、学術論文、主要出版社・学術出版社の研究書、複数の書評/引用がある候補など
- `優先: 中`: 関連性は高いが、本文未確認、媒体・著者属性の追加確認が必要、または一般向け解説
- `優先: 低`: 探索ヒント、読者レビュー、検索スニペット、周辺候補
- `優先: 保留`: タイトルや論点は強いが、媒体・著者・本文・引用/書評状況が未確認で判断保留
`優先` は調査上の確認順であり、文献の価値確定ではない。出版社・媒体・シリーズだけで文献の価値を確定しない。自費出版・個人出版支援・オンデマンド出版系、個人出版、通俗的媒体は通常、二次文献・解説的媒体として慎重に扱う。タイトルや論点が直接一致しても、主題一致だけで `優先: 高` にしない。著者属性、本文の史料処理、引用・書評状況、専門的な批判・応答を確認するまでは `優先: 中` または `優先: 保留` に置く。ただし、著者が当事者である、刊行時期が論争や出来事と近い、本文が同時代証言や受容史を示す、といった条件が確認できる場合は、調査上の価値を個別に評価して残す。
根拠種別と用途:
- `本文`: 内容把握の強い根拠
- `要旨`: 内容把握の中程度の根拠。ただし要旨の範囲に限定
- `目次`: 扱う論点・構成の根拠。本文結論の根拠にはしない
- `DB件名`: 主題推定・検索語展開の根拠
- `学術書評` / `専門誌書評`: 受容・評価・批判・論点整理の強い候補。学会誌・研究会誌・紀要・専門誌の書評は研究論文・論争文献に準じて文献候補に含める。ただし書評本文を読んだかは別に示す
- `引用・参照`: 分野内での受容・重要度の候補。引用のされ方は追加確認が必要
- `出版社紹介`: 内容紹介の根拠。評価根拠としては弱い
- `レファ協/図書館情報`: 調査ルート、存在確認、所蔵確認の根拠
- `研究者ページ`: 業績・関連成果の手がかり。更新状態に注意
- `個人Web/ブログ`: 発信者確認後、専門家による二次情報になりうる
- `Web補助確認`: 出版社・団体の性格、著者属性、本文入口、公式PDF所在、DB外の専門的反応を補う材料。文献DB由来の書誌・要旨・目次と混同しない
- `読者レビュー`: 原則として探索ヒント。学術的評価の根拠にしない
- `SNS/検索スニペット`: 最低レベルの手がかり。本文理解や評価の根拠にしない
個人 Web、ブログ、note を根拠として使う場合は、プロフィール、実名または継続的な筆名、所属・肩書、専門分野、researchmap / KAKEN / CiNii / ORCID / 大学ページ等へのリンク、当該テーマとの関連、記事内の出典・引用・ページ番号・書誌情報を最低限確認する。発信者確認ができない場合は探索上の手がかりに留め、`次: 発信者プロフィール確認` とする。
Web調査は通常、文献候補を作る主経路ではなく補助確認である。ユーザーが「Webで書評を探して」など明示した場合、またはDB上で専門的書評・批判・応答の存在が示唆された場合を除き、Webを広く巡回して候補集合を作らない。Webを使った場合は、何を確認したのかを `出版社・団体の性格`、`著者属性`、`本文入口`、`専門的反応` のように分けて書く。
刊行直後の反応、論争、イベント、未発表資料への言及を速報Web検索で見つけた場合、`agent_web` / `ephemeral` は調査経路の証拠として扱う。bibliographic evidence、要旨、目次、fulltext evidenceの代わりにはしない。通常は、正式 source で確認するための `next_actions[].evidence_refs`、または確認事項を残す `open_questions[].evidence_refs` に置く。投稿だけを根拠に候補を採用せず、候補判断へ結び付ける場合も `needs_followup` とする。詳細は `04-ephemeral-web-discovery.md` を読む。
Amazon レビュー、読書メーター、匿名レビュー、SNS 短文、検索スニペットは、原則として探索ヒントに留める。学術的評価・内容把握・立場分類の根拠にしない。使う場合は `根拠: 読者レビュー` のように明示する。
学会誌・研究会誌・紀要・専門誌の書評、リプライ、書評論文、紹介、批判的検討は、タイトルに「書評」「紹介」が含まれていても機械的に落とさない。対象文献が主題の中心文献である場合、または論争の受容・批判・論点整理を含む可能性がある場合は、少なくとも `保留・弱い除外候補` に残し、内容次第で `主要候補` に上げる。媒体・著者・本文・注の確認で内容が薄いと分かった場合だけ除外する。
中心文献の主張や論争上の位置づけを評価するときは、対象文献そのものと専門的書評・批判・応答をセットで探す。検索語には `書評`、著者名、書名、主要キーワードを組み合わせる。書評を見つけた場合は、一般レビューではなく `根拠: 学術書評` / `根拠: 専門誌書評` として扱い、媒体名を必ず示す。
長い注意書きは毎件付けない。詳しい注意は、ユーザーが「信用できるか」「どう位置づけるか」と聞いた場合、代表文献候補・引用候補に格上げする場合、根拠が本文ではないのに強い内容把握に見えそうな場合、タイトルが強く断定的・論争的な場合、個人 Web・ブログ・読者レビューを根拠として使う場合、出版社・媒体・査読・引用状況が判断に関わる場合に限る。
## 初出・再録・最終版候補
発行日は版関係を推定する重要な手がかりだが、唯一の根拠にしない。
- 初出候補: もっとも早い発行日、雑誌・紀要・学会誌等に掲載
- 再録候補: 後年の図書・論文集・著作集・全集に同題または近似題で収録
- 改稿・増補候補: 初出一覧・あとがき・版注記に「改稿」「補訂」「増補」等がある
- 最終版候補: 後年収録で、著者自身の単著・著作集等に入り、版注記も確認できる
- 要現物確認: 目次・初出一覧・あとがき・本文差分が未確認
後年の収録書が見つかった場合も、現物未確認なら「最終版」と断定しない。文献自体の存在確認と、版関係の確認は分ける。報告では、発行日、収録書名、収録箇所、確認できた注記、未確認点を分けて書く。
## researchmap 由来情報
researchmap 個人ページで見つけた講演・口頭発表・寄稿・分担執筆・MISC 等は、原則として「追加探索の手がかり」として扱う。
- 文献探索中に重要そうな著者が見つかり、その著者の researchmap 個人ページを確認した場合は、「著者から辿った補助確認」として報告する。
- researchmap は研究者本人・機関による更新状況に左右される。ページや業績一覧の更新日が古い場合、最新情報の欠落を明記する。
- CiNii / J-STAGE / IRDB / NDL / DOI / ISBN で確認できた場合だけ、文献候補として格上げする。
- 口頭発表や講演は、文献ではなく活動記録として分けて報告する。
- researchmap の記載だけを根拠に、確認済み書誌・引用可能文献として扱わない。
- 報告時は「researchmap 個人ページ由来」と明記し、個人ページ URL、確認できた更新状態、次に確認すべき DB や検索語を添える。
## 候補提示時に添える情報
文献候補を列挙する場合、各項目に最低限次を付ける。取れない項目は省略せず、`不明` / `未確認` / `DB上は未取得` のように状態を示す。
- 書誌: 著者「論文名」『掲載誌名』巻号, 発行元, 年 / 著者『書名』出版社, 年
- source: DB名 + URL または `source_id`
- `候補確度`: 書誌確認済み / 有力候補 / 弱い候補 / 関連性未確定
- `確認`: 書誌 / 要旨 / 目次 / 本文 / 引用経由 / 検索ヒットのみ
- `本文`: 未確認 / オンライン入口あり未読 / オンライン入口なし / アクセス制限 / 確認済み
- `優先`: 高 / 中 / 低 / 保留
- `根拠`: 要旨 / DB件名 / 目次 / 本文 / 学術書評 / 専門誌書評 / 出版社紹介 / 検索結果スニペット など
### API / browser / fulltext 候補の統合表示
`jp_lit_search`、`jp_lit_search_fulltext`、`jp_lit_record_ndl_browser_search` が同じ canonical `source` + `source_id` を返した場合、経路別に候補一覧を分断せず、一つの候補リストで一件として示す。各 item には次を残す。
- `発見経路`: NDL Search API / 次世代デジタルライブラリー全文検索 / デジコレ本体の全文検索(browser)のうち実際に確認したもの
- `access`: `access_scope` と公式画面の `access_label`
- `content`: `content_state`。`page_image_checked` だけを本文画像の実見として扱う
- `fulltext`: `item_fulltext_state` と `hit_locations`。`searched` は資料内全文検索を実行した状態
- `print`: `print_file_state`。`dialog_available` / `generation_requested` / `pdf_ready` / `saved` を別状態として表示する
複数の browser observation がある場合、表示上の現在状態は `checked_at` が最新の観測を使い、JSON export では履歴をすべて保つ。検索概要と調査ログでは API / browser / fulltext の total、取得件数、確認日時を分ける。
```md
1. 斉藤隆夫『帝国憲法大要』憲政公論社, 1926
- source: NDLデジタルコレクション, R100000039-I1907653
- 発見経路: NDL Search API / 次世代デジタルライブラリー全文検索 / デジコレ本体の全文検索(browser)
- access: individual_transmission(個人送信で閲覧可能)
- content: page_image_checked
- fulltext: searched(67–73コマ)
- print: dialog_available
```
### 標準出力構成
文献リストを返すときは、原則として次の見出し順にする。ユーザーが短い回答を求めた場合でも、`検索概要`、`今回の確認範囲`、`調査ログ` は圧縮して残す。レファ協・リサーチ・ナビで参考図書・専門索引・有料 DB が示唆された場合は、`参考書誌・有料DBの次アクション` も残す。
1. `検索概要`
2. `主要候補`
3. `保留・弱い除外候補`
4. `除外した代表例`(明確な除外がある場合)
5. `参考書誌・有料DBの次アクション`
6. `今回の確認範囲`
7. `調査ログ`
候補が少ない場合でも、`保留・弱い除外候補: なし(理由: ...)` のように明示し、単に省略しない。`除外した代表例` は、明確な除外がある場合に出す。明確な除外がない場合や未点検の場合は、検索概要または確認範囲に `明確な除外代表なし` / `除外代表は未点検` と書く。
`参考書誌・有料DBの次アクション` では、無料オンラインで確認できた範囲と分けて、次に見るべき参考図書・専門索引・契約 DB、そこで試す検索語、今回未確認であることを示す。MCP の `source` として扱わず、人間が次に確認する動線として書く。示唆がない場合は `なし(今回の調査前情報収集では示唆なし)` とする。
### リスト出力形式
文献候補をリスト出力する場合は、説明文の自由度を下げ、各項目の体裁を統一する。原則として次の形式を使う。
```md
1. 著者「論文名」『掲載誌名』巻号, 発行元, 年
- 種別: 論文 / 雑誌記事 / 図書 / 学術書評 / 書評論文 / 紀要論文 / 研究ノート / その他
- source: DB名, URL または source_id
- 候補確度: 書誌確認済み / 有力候補 / 弱い候補 / 関連性未確定
- 確認: 書誌 / 要旨 / 目次 / 本文 / 引用経由 / 検索ヒットのみ
- 本文: 未確認 / オンライン入口あり未読 / オンライン入口なし / アクセス制限 / 確認済み
- 優先: 高 / 中 / 低 / 保留
- 根拠: 要旨 / DB件名 / 目次 / 本文 / 学術書評 / 専門誌書評 / 出版社紹介 / 検索結果スニペット
- 仮整理: 本文未読の場合は、探索上の位置づけだけを短く書く
- 次: 必要なら次に確認すること
```
図書の場合は 1 行目を `著者『書名』出版社, 年` にする。巻号・発行元などが DB から取れない場合も項目の順序は保ち、`不明` / `DB上は未取得` と明示する。候補ごとに項目名や順番を変えない。
必要に応じて次も付ける。
- `仮整理` / `次` の短いラベル
- 初出 / 再録 / 改稿・増補 / 最終版候補 / 要現物確認のラベル
- 初出候補の掲載誌・発行年
- 後年収録候補の書名・出版社・発行年
- 目次・初出一覧・あとがき・版注記の確認状況
- 所蔵館・複写可否の次アクション
本文を読んでいない場合は、内容評価ではなく `仮整理` として書く。`availability.online=true` はオンライン入口であり、本文読了を意味しない。
### 表示区分
採用候補だけを出すと調査の幅が見えにくい。文献リストは原則として次の 3 区分に分ける。
- `主要候補`: 関連性が高く、まず確認すべきもの
- `保留・弱い除外候補`: 関連しそうだが、今回の条件から少し外れる、本文未確認で判断が弱い、周辺文献だが見落とすと困るもの。学術誌・紀要・専門誌の書評や紹介記事も、論争文献の受容・批判に関わる可能性があればここに残す
- `除外した代表例`: 明確に主題外、年代外、重複、資料種別違いなど
`保留・弱い除外候補` は、出力件数が少なくなりすぎる場合や、除外理由が強くない場合に必ず数件示す。除外理由が弱いものを完全に隠さない。
## 短い抜粋の添え方
書誌要素だけでなく、候補の関連箇所を短く示す。
- `jp_lit_search_fulltext` の `highlights` があれば、上位候補に 1〜2 件添える
- `jp_lit_search` / `jp_lit_get_record` の `summary` があれば短く添える
- `table_of_contents` が有用なら代表的な項目だけ添える
目的は「なぜその候補を出したか」をその場で分かるようにすること。毎件長く貼り付けず、上位候補だけに短く付ける。ページ番号が必要なら `jp_lit_search_pages` を追加で使う。
## 選別過程の明示
必ず次を説明する。
- 文献候補リストの前に `検索概要` を置く
- 今回の返答が何回の検索を束ねたものか
- 各検索で何を確かめるために source / query を変えたか
- 各 source から何件取得したか
- 取得件数と表示件数を分ける(例: `全22件中22件取得、主要候補5件・保留3件を表示`)
- どの基準で候補を絞ったか
- 除外したものがあればその理由。理由が強くないものは `保留・弱い除外候補` として見せる
- `jp_lit_refine_results` を使った場合は、`total_before` / `total_after` と適用した条件(sort/filter)を明示する
- `jp_lit_refine_results` は既定で先頭 30 件だけ返す。`total_after > 30` の場合は、「全何件中、どの順の先頭 30 件か」を明示する
- 全件確認が必要な場合は、まず `jp_lit_export_view` で書き出す
- 重複確認は通常の再整理に毎回混ぜない。必要なときだけ `include_duplicate_clusters=true`、全件確認では `jp_lit_export_view(view="refined_results", export_all=true, duplicate_notes=true)` を使う
- `total_after > 100`、複数 cache 統合後の傾向要約、または独立した調査線が複数ある場合は、`cache_key` / `session_id` と担当範囲を固定したうえでサブエージェント分担を検討する。各担当は担当範囲の trace と調査トレース報告 / handoff report を残し、最終判断は主エージェントが統合する
検索概要の最小形:
```md
## 検索概要
- 検索回数: N回
- 使用source: cinii_articles / ndl_articles / ndl_catalog など
- 検索語: 実際に使った query
- 取得件数: 各検索について「全N件中M件取得」
- 表示件数: 主要候補X件、保留・弱い除外候補Y件、除外代表Z件
- 選別基準: 関連性、年代、重複、資料種別、本文確認状態など
```
返答末尾に `今回の確認範囲` を置く。
```md
## 今回の確認範囲
DB書誌確認が中心。本文確認済みは0件。要旨確認は1件。オンライン入口あり未読は2件。
```
続けて `調査ログ` を置く。`total` は検索元が返した総ヒット数、`取得件数` は実際に取得・表示候補化のため読めた件数、`抽出件数` は主要候補・保留候補・除外代表などに選別した件数として分ける。
```md
## 調査ログ
| # | source | query | total | 取得件数 | 抽出件数 | 備考 |
| --- | --- | --- | ---: | ---: | ---: | --- |
| 1 | ndl_catalog | 賭博 近世 | 42 | 20 | 5 | page=1 のみ確認 |
```
検索しなかった場合も省略せず、`調査ログ: 今回は検索なし(理由: 既存候補の表示形式だけを変更したため)` のように明示する。
### 取得失敗や停止を含む報告
取得失敗・アクセス停止・部分成功が調査範囲に影響した場合は、既存の出力構成に次の情報を加える。経路判断とtoolへの保存方法は [失敗時の手順](../heuristics/failure-modes.md#取得失敗アクセス停止時の手順)を使う。
- `検索概要`: 成功した経路と失敗・停止した経路、実際に得た候補数を示す。
- `今回の確認範囲`: 停止や切替の判断根拠、未確認範囲、次に使える正規の経路を示す。
- `調査ログ`: sourceまたはサービス、API・Web・公式画面の別、検索語、観測日時、応答、件数を残す。規約・robots.txt・画面表示を判断根拠にした場合は、参照先と確認日時も記す。
次は架空の部分成功例である。HTTP statusが出力されなかった経路は、その確認状態を保って報告する。
```md
## 検索概要
API検索2経路のうち、NDL Searchでは候補3件を取得。J-STAGEはHTTPエラーで取得失敗。
## 今回の確認範囲
NDL Searchの候補3件は書誌まで確認。本文とJ-STAGE側の候補・総ヒット数は未確認。
browser toolを利用できないため公式画面は未確認。次は利用者がJ-STAGE公式画面で同じ検索語を確認する。
## 調査ログ
| 経路 / source | query | 観測日時 | 応答 | total | 取得件数 | 抽出件数 |
| --- | --- | --- | --- | ---: | ---: | ---: |
| API / ndl_search | 普通選挙法 | 2026-11-16T10:00:00+09:00 | 正常 | 3 | 3 | 3 |
| API / jstage_articles | 普通選挙法 | 2026-11-16T10:01:00+09:00 | HTTPエラー、status未提供、原因未確定 | 不明 | 0 | 0 |
```
件数は確認できた範囲に対応させる。取得失敗の `total` は「不明」、検索未実施は「未実施」とし、正常0件と分ける。公式画面で一部候補を確認後に停止した場合は「2件確認、総ヒット数不明、次ページ以降は未確認」のように書く。総件数未観測のbrowser記録が返す `total` は観測件数の下限であり、全体の総ヒット数へ置き換えない。
## rolling checkpoint
長期調査では、あとから現在地を復元できるように rolling checkpoint を残す。
```md
## rolling checkpoint
- 調査目的と現在の scope:
- 採用候補:
- 保留候補:
- 検索ヒットのみ候補:
- 本文確認済み / 目次確認 / 書誌確認 / 未確認の区別:
- 試した検索語:
- 有効だった検索語:
- ノイズ語・除外理由:
- source ごとの total / 取得件数 / 抽出件数:
- 未確認事項:
- 次アクション:
- cache key / session id / 関連ファイル:
```
checkpoint は最終結論ではない。本文未読資料を本文確認済み扱いせず、検索ヒットのみ候補を関連文献と断定せず、複合語 0 件を不在証明にしない。
## サブエージェント分担契約
サブエージェントまたは sequential 担当単位へ分ける場合、環境固有の呼び出し API に依存しない契約として次を渡す。主エージェントが統合判断を持ち続ける。
```md
## サブエージェント担当依頼
- 担当範囲:
- 調査目的:
- 使用してよい source:
- 検索語候補:
- 既知の確認済み事項:
- 除外してよいノイズ:
- 禁止事項:
- 本文未読資料を本文確認済み扱いしない
- 検索ヒットのみを関連文献と断定しない
- 複合語 0 件を不在証明にしない
- 必須出力:
- 検索語
- source
- total / 取得件数 / 抽出件数
- 採用候補
- 保留候補
- 除外語・ノイズ
- 本文確認範囲
- 未確認事項
- 次アクション
```
## 調査トレース報告
調査トレース報告 / handoff report は、主エージェントが読むための整理済み調査報告である。cache は検索結果・取得 payload の保管場所、低レベル trace は tool call や実行イベントを含む機械寄り記録として分ける。サブエージェントは cache があることだけで完了扱いにせず、担当範囲の判断を report として返す。
サブエージェントに任せた場合、主エージェントへ返す report には最低限次を入れる。単独エージェントの長い調査でも、あとで研究ノートに育てる可能性がある場合は同じ形式を使ってよい。
```md
## 調査トレース報告
- 担当範囲:
- session_id:
- cache_key:
- 使用 source:
- 検索語:
- 件数の読み方:
- total:
- 取得件数:
- 抽出件数:
- 主な検索試行:
- 採用候補:
- 保留候補:
- 除外理由:
- 本文確認範囲:
- 根拠参照:
- cache_key / source_id / URL:
- 未確認事項:
- 主エージェントへの判断ポイント:
## 変更履歴
- YYYY-MM-DD: 変更内容
```
report 内では、total は検索元が返した総ヒット数、取得件数は実際に取得して読めた件数、抽出件数は主要候補・保留候補・除外代表などへ選別した件数として書く。`extracted_count` などのツール由来 count を検索総件数と混同しない。
追加プロンプトで訂正・追補が入った場合、report 本文は current report として最新版に更新してよい。時系列は本文に混ぜ込まず、`変更履歴` に「何を、なぜ直したか」を短く残す。
## 重複クラスタ確認
- クラスタは自動削除ではなく、同一候補の確認材料として扱う
- `duplicate_key` と title/author/year の近似一致から候補を出す
- `search_result_readiness` は検索結果レベルのメタデータ充足度であり、引用確定には詳細レコードや現物確認が必要
- サブエージェントを使う場合も、対象 `cache_key` / `session_id` と担当範囲を固定する。各担当は検索ログ・採否理由・未確認事項を trace と調査トレース報告に残し、最終採否は主エージェントが統合してユーザーに確認する
- CSL JSON へ渡す前は、重複候補を見たうえで採用項目だけを `jp_lit_annotate_session(session_id=SID, ...)` に保存し、`jp_lit_export_session(session_id=SID, format="csl-json", profile="selected")` で書き出す
## annotation / export
- `selected_items.note`: 個別候補の短い理由
- `notes`: 検索全体の選別理由
- 何件取得して何件を採用したか
- 何回検索し、各検索で何を確かめたか
- どの基準で絞ったか
- 外したものの代表的な理由
- 次に何を確認すべきか
- `jp_lit_update_session_trace(session_id=SID, ...)`: 明示した session 全体の調査目的、scope、source plan、未確認事項、次アクション。未確認事項・次アクションが特定候補に紐づく場合は `evidence_refs[]` に `cache_key` / `source_id` / URL を残す
- 速報Web発見は `evidence_refs[]` の `evidence_type=agent_web` / `stability=ephemeral` として保存し、投稿の確認時刻と親trace要素の保存時刻を分ける
- `jp_lit_annotate_session.trace.agent_label` / `task_scope`: サブエージェントや担当範囲
- `jp_lit_annotate_session.trace.search_attempt`: その検索で使った source / query、目的、total、取得件数、抽出件数、結果
- `jp_lit_annotate_session.trace.decisions`: 採用・保留・除外・重複・要追加確認の理由と根拠
- `jp_lit_annotate_session.trace.evidence_scope`: 候補ごとに `metadata` / `abstract` / `toc` / `fulltext_snippet` / `fulltext` のどこまで見たか
- `CSL JSON には trace を混ぜない`。Markdown / JSON export には調査経過を含めるが、文献管理向け CSL JSON は採用文献の書誌配列に限定する
`jp_lit_export_session` の profile:
- `full_log`
- `selected`
- `unselected`
- `methods`: 検索条件ごとの最新保存entryから調査方法を出力する。対応formatはMarkdown / JSON
`methods` は機械が記録した検索条件・件数根拠と、agentが申告した目的・判断を区別する。取得時contextがない旧cacheは欠落を残し、全実行履歴、全件収集、本文確認を保証しない。CSL JSONには対応しない。詳細と呼び出し例は[使い方ガイド](https://github.com/itarunnn/jp-lit-mcp/blob/main/docs/usage-guide.md#検索条件と調査方法を保存する)を参照する。
## 参照
- `01-core-workflow.md`
- `02-source-and-query.md`
- `04-ephemeral-web-discovery.md`
- 旧詳細資料: `heuristics/evidence-grading.md`, `heuristics/db-characteristics.md`, `heuristics/clarifying-questions.md`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |