Research Graph

---
description: 設計・手法・技術選定の見立てを、業界/学界の一次情報で校正してからドメイン最適化する調査ループのグラフ実行版（/research-loop と同じ目的・同じ記録の形）。起動するのは、人が /research-graph と打ったときか「工程に回して」と言ったときだけ——AI は自分から起動せず、設計文書の論拠固め・技術選定・方式検討・直し方の見立ての校正に当たったら人に提案する。回す手順は機械（engine）が持ち、この手順書は engine の呼び方だけを書く。コード変更のレビューには使わない。
allowed-tools: Bash, Agent, Read, Write, Edit, Grep, Glob, WebSearch, WebFetch
---

# research-graph

## これは何か

見立て文書（設計・手法・技術選定の仮説を書いた文書。`init` の `--document` に渡す）の中の「外部に照合できる主張」を一次情報で判定させ、訂正を統合し、独立の目のゲートを通して、新しい相違が出なくなるまで回す調査ループである。この本文が読み込まれているのは、人が `/research-graph` と打ったか「工程に回して」と言った後で、回すのはあなたである。convergence-loops の `/research-loop` と目的も記録の形も同じで、違いは手順の置き場だけ——散文の手順書の代わりに、グラフ（`graphs/research-loop.json`: ノード・依存・役・プロンプト・返答の型）を engine（`scripts/loop.py`）が読み、盤面（どのノードが終わったか・何周目か）・同時に走らせてよい組・渡してはいけないもの・件数の突合・連続カウント・上限・止める条件を機械が持つ。ループの算術と記録の正本の置き場は [references/exits.md](references/exits.md) の「終わり」。

このループを回す session が **surveyor**（調査者・統合者）で、それはあなたである。あなたがするのは判断作業だけ——問いと制約の棚卸し・主張の棚卸し・訂正の統合・ドメイン適応（校正した定石を、この依頼の分野の制約に合わせて直す。説明文の「ドメイン最適化」）・報告。判定（確証・相違・留保・検証不能）は一切しない。判定は別 context の役割 agent が返し、engine がそれを記録に写す。

役の起動方法（engine が起動する役と、起動できない役を Agent で起動するとき）は [references/nodes.md](references/nodes.md) の頭に在る。

このプラグインの置き場（この SKILL.md があるフォルダの 2 つ上）は `${CLAUDE_PLUGIN_ROOT}` である（ここと下のコマンドの中はスキルを読み込んだ時に実際のパスへ置き換わる）。下の `references/` はこのファイルと同じフォルダにある。別ファイルのコマンドに書いた `CLAUDE_PLUGIN_ROOT`（`$` と波括弧で囲んだ形）は置き換わらず Bash の環境変数にも無いので、ここに出たパス（置き換わらずに見えているなら、この SKILL.md があるフォルダの 2 つ上）に読み替えて打て。コマンドは書いた形で打ち、`python3` に替えない（`hooks/run-python.sh` が、Windows の Store へ誘う `python3` を飛ばして 3.12 以上を選ぶ）。

## 手順

1. **始める**。依頼文と見立て文書を渡して盤面を作る:

   ```bash
   bash "${CLAUDE_PLUGIN_ROOT}/hooks/run-python.sh" "${CLAUDE_PLUGIN_ROOT}/scripts/loop.py" init --loop research-loop --request @<依頼文のファイル> --document <見立て文書>
   ```

   返ってきた `dir`（盤面の置き場）を **以降の全部の呼び出しに `--dir <DIR>` で渡せ**。省くと engine は `current` から推測するが、同じリポジトリに別の run が在ると取り違えて拒む（別ループの run が並ぶと exit 2）。名指しが既定の導線である。

   `--request` は文字列でもよい。段は既定で標準。**軽量にしてよいのは依頼者がそう言ったときだけ**で、そのときに限り `--thickness light --decider requester` を添える（段と decider はキー。表示の語〔軽量・依頼者指定〕で打っても engine がキーに直す）（回す側の判断で下げる道は無い。engine が拒む）。N 周目の締めの後で次の周を開かずに止めるなら `--stop-after-round N`（`status` が stopped、`halted` が `by: stop_after_round`。止めた後の `next` はノードを出さない。次の周へ進めるなら `loop.py resume --reason "<理由>" --stop-after-round <次に止める周>`（止めずに回すなら `--no-stop-after-round`）——続けられるのは周の数で止めた run だけで、盤面を直に書き換える `loop.py patch` で開けるな）。無人で走るなら `--unattended`（人に聞くターンになったら保守的に止まり、聞きたかったことを報告に載せる）。返ってきた `overview` を読め——ループ全体の形はここだけで渡す。

2. **回す**。`loop.py run` を**前景で**打つ（Bash の timeout は最大に）。engine が起動できるノード（役・走らせるだけのノード・sandbox の中で起動する任せ先〔下請けの子〕）は、回し手（run が会話の Bash から切り離して立てる engine の背景プロセス）が起動して受け付けまで進め、run は止まる所でだけ戻る。回し手は 1 つの run に 1 本だけで（盤面の置き場の錠で決まる。2 本目の run は回し手を立てずに付き添う）、見守りの run が Bash の上限に当たって止められても背景へ移されても、回し手と役は止まらない:

   ```bash
   bash "${CLAUDE_PLUGIN_ROOT}/hooks/run-python.sh" "${CLAUDE_PLUGIN_ROOT}/scripts/loop.py" run --dir <DIR>
   ```

   終了コードで次の手を決めよ（値の表の正本は engine の `runner.CODES`）:
   - **20**（まだ回っている。540 秒で戻る）——何もせずにもう一度 `run`
   - **13**（会話に返すノードがある）——出力の `handoff` のノードを [references/nodes.md](references/nodes.md) のノードの種類のとおりにこなし（`launch` を持つノードは `loop.py launch`、持たない agent は Agent ツールで起動し、runner のノード〔あなたの判断の仕事〕はあなたがやる）、返答を `loop.py done` で engine に返し、もう一度 `run`。回し手は他のノードを回し続けている
   - **10**（人の答え待ち）——`ask` の中身を散文で人に見せ（選択肢だけ並べない。[references/human.md](references/human.md) の「人に聞くターン」）、答えを `loop.py answer` で返してからもう一度 `run`
   - **0**（終わった）・**11**（init の `--stop-after-round` の周で止めた）・**12**（進めない。`detail` を読む）・**14**（人が確かめる事がある。`needs_human` を人に見せる）——ここで初めてターンを終えてよい
   - **1・2**（run そのものが拒まれた・盤面が読めない）は標準エラーを読んで直してから、**128 以上**（信号で止まった）はそのまま、もう一度 `run`——続きは盤面から拾う

## 場面ごとに読むファイル

**下の場面では、そのファイルを読んでから手を動かせ。**

- `run` の出力の中身・`next`（次に回せるノードを出す）で回すとき・`run` が 13 で戻り `handoff`（会話に返すノード）をこなすとき・`done`（ノードの返答を engine に返す）: [references/nodes.md](references/nodes.md)
- `run` が 10 で戻った・人に聞くターン（`loop.py answer` と聞き方）・人が途中で止める・run の子（engine が起動した `claude -p`）の残りを止める: [references/human.md](references/human.md)
- 開いた問いを deep-research に回す・段を上げる・ノードを省く・終わり（報告）: [references/exits.md](references/exits.md)
- プラグインの版を上げたとき・作業ツリーの変化で `done` が拒まれた・報告の言語: [references/rules.md](references/rules.md)
- 人の方針（どの run にも効く人の決まりの文書）の置き場・どのノードに本文が貼られ、どれに置き場だけが渡るか・run の途中の書き換えの扱いを確かめるとき: [references/policy.md](references/policy.md)

## どのターンでも

- 記録（`record.json`）を直接編集しない。判定のフィールドは役の返答から engine だけが書く。
- 済んだノードに `done` し直さない（同じ周で回し直して有利な判定を採らない。やり直しは次の周）。
- 会話が圧縮されて場所を見失ったら `loop.py status --dir <DIR>` → `loop.py next --dir <DIR>`。盤面はディスクにある。
- **engine の出力を会話から外さない**（`> file` へ落として読まない形にしない）。見立て文書を読んだかの確かめは、この session の転写（Claude Code がこの会話を書き残すログ）に残るツールの結果を engine が読んで判断する——engine を回した出力そのものが「この run を回したのは会話の主〔見立て文書を読んだこの会話〕である」印になっているので、出力を捨てると確かめが成立せず、その回は「確かめられなかった」として記録に残る（読んでいないのに通るわけではない。確かめが立たないだけで、痕跡は報告に出る）。同じ理由で、**engine を回した出力が会話に残らない場から回すと確かめは成立しない**（台本や別のプロセスから回した場と、この会話自体が別の会話に頼まれた下請け〔サブエージェント〕の場を含む）——確かめさせたいなら、engine の出力が会話に出る場から回せ。engine は転写の由来を判定していないので、これは engine の保証ではなく、出力が転写に載るかどうかの話である。
- **回す側の手の心得**（人の居ないターンで止まらない・取り違えない）: ①手順書が命じていない消す操作（一時の写しの片付けを含む）は、人の居ないターンで打たない——許可の問いは主の会話に出るので、答える人が居なければそこで止まり続ける（実測 2026-09-27: 最後に一時の写しを消すコマンドが許可待ちになり 50 分止まった）。写しは消さず、置き場を報告に書いて人に渡せ。②背景に回すのはハーネスの Bash の背景実行で、シェルの `&` ではない——背景実行なら作業に ID が付き、止める口と出力を引く口をハーネスが持つ。③ノードと線の結果は盤面で見る。背景の作業の出力で判断しない（別の背景の作業の出力と取り違える）。待つのは `run` の終了コードである。