task-research reference

task-research は、Issue 作成、既存 Issue 実装、Issue なし local plan 実装の前に read-only 調査を行い、下流 skill が再利用できる research packet を作る入口である。 Issue 作成、コード編集、commit、push、PR 作成、review 対応は行わない。

詳細 schema は task-research contract と claude/skills/task-research/SKILL.md を source of truth とし、この文書は利用者向けの引数早見表として扱う。

通常経路

1. target= と research= で調査対象と深度を決める。
2. コードや docs を read-only で調べ、research-plan.json、research-packet.json、research-brief.md を作る。
3. 既存 packet を使う場合は validator で整合性と凍結済みのユーザー判断を確認する。
4. handoff=... を指定した場合も下流 skill は起動せず、次に実行する resume command だけを handoff.json に残す。

未指定の出力先は repo identity scoped user state root 配下の repositories/<repo-key>/artifacts/task-research/<id> である。out=<dir> を明示した場合はその directory を使い、既存の tmp/task-research/<id> は legacy fallback 候補として読むだけで、自動移動や削除はしない。

停止と復旧

• high-impact な未確定事項が残る場合は /grill-me research-packet=<path> で interview に戻すか、現在の会話でユーザー判断を記録する。
• research-mode=parallel の worker が unavailable または timeout になった場合は成功扱いにしない。原因を解消して再実行するか、利用者が実行方式を選び直す。
• 既存 packet が invalid または stale の場合は task-research validate の結果に従い、packet の修正か再調査へ戻る。
• blocked_options が残る handoff は成功ではない。渡し先が消費できる option に直して resume command を作り直す。

利用者が選ぶのは、調査深度、single / parallel の実行方式、handoff 先、出力先である。

research depth

research=auto は research-plan.json に resolved_depth、reasons、required_outputs を残す。 深度は local reviewer 用 agents=、GitHub reviewer / trigger selector の reviewers=、validation 用 agent= とは別の概念である。

research mode

research-mode= は実行方式であり、research= の調査深度とは別の概念である。research=deep は高度な調査深度を表すが、それだけで parallel worker 実行を意味しない。 research-mode=parallel を推奨するのは research=deep の時だけである。light / standard / spike では、ユーザー明示または上位 workflow の理由がある場合だけ使う。

research-mode=parallel の worker 数も固定値ではない。明示指定がなければ resolved_depth に応じて light=1、standard=2、spike=1、deep=必要な観点数に応じて 3 以上 に解決し、research-workers.json に worker_count_source: "auto_by_depth" と理由を残す。deep でも runtime 上限までの起動は強制せず、呼び出し側の AI Agent が調査観点とリスクから必要数を判断する。明示 override の場合は worker_count_source: "explicit" とする。

明示 research-mode=parallel で worker が unavailable / timeout になった場合、silent fallback で成功扱いにしない。timeout は短くせず、30 分程度を既定目安にする。

worker は read-only discovery だけを行い、Issue 作成、コード編集、test 追加、format、commit、push、PR 作成、GitHub comment を行わない。

input

research-packet=<path> を指定した場合は、調査前に review-orchestrator task-research validate --packet <path> を実行する。 入力 packet の decisions[] と source_facts[] は新しい packet の根拠として引き継げるが、chosen_by: "user" の decision は凍結済みとして上書きしない。

既存 packet から新しい packet を作った場合は、出力後に review-orchestrator task-research validate --packet <new-packet> --prior-packet <input-packet> を実行する。prior packet の user decision が新しい packet に chosen_by: "user" として残っていなければ blocked になる。

既存 Issue や Issue 起票前 target に対応する packet 候補を探す場合は、review-orchestrator task-research discover --issue <num|url> --repo <owner/repo> または review-orchestrator task-research discover --target <text> --repo <owner/repo> を使う。discover は task-research-discovery.v1 JSON に path/ref、digest、target、validation status、stale reason、candidate status だけを返し、packet 本文や private context は返さない。

high-impact な chosen_by: "agent" decision や handoff に影響する unresolved_questions[] が残る場合は、下流実行前に /grill-me research-packet=<path> で interview に戻せるよう question_adequacy_audit.passed=false かつ required_before_handoff[] に残す。

high-impact な未確定事項は /grill-me へ戻すのが既定だが、現在の会話でユーザーが直接回答できる場合は、その質問と回答、確認日を evidence に残し、decisions[] へ chosen_by: "user" として記録できる。直接確認後も task-research validate、必要な grill gate、下流 readiness / validation gate は省略しない。

handoff

handoff は下流 skill を実行せず、handoff.json に target_skill、research_packet_path、任意の research_packet_ref、resume_command、consumed_options、blocked_options を残す。 research_packet_path は既存互換の repo 相対 path とし、user state root 配下の packet は research_packet_ref に state-root-relative ref として残す。

blocked_options がある場合は handoff 成功扱いにしない。

agent= の扱いは handoff 先ごとに次のとおり。

• agent=claude などを handoff=github-issue-breakdown と一緒に指定した場合、resume_command は /github-issue-breakdown research-packet=... agent=claude の形にする。この agent= は downstream option なので、consumed_options には入れない。有効な値なら blocked_options にも入れない。
• handoff=implement-from-plan agent=claude の場合も、agent= は plan validation selector として /implement-from-plan research-packet=... agent=claude の形で resume command に残し、consumed_options と blocked_options には入れない。
• handoff=fix-github-issue agent=claude の場合は、fix-github-issue に agent= の消費先がないため blocked_options に入れて handoff 成功扱いにしない。

詳細 contract

調査から managed Issue 作成 family へ進む場合、進捗と完了は review-orchestrator issue workflow-family-status の issue-workflow-family.v1 JSON で確認する。packet や handoff の存在だけでは、validation、Issue create、post-create、sub-issue link、parent finalization の完了証跡にならない。

同じ時点の独立 gate は既存 command を同じ shell request で実行し、各 stdout schema の terminal field を一括評価する。前段の結果で後段の引数が決まる command と mutation は別 request に分ける。

artifacts

research packet は、一次情報、候補ファイル、既存 contract、採用方針、代替案、未解決質問、検証候補をまとめた再利用用の調査メモである。 research-brief.md は人間が読む要約で、research-packet.json は下流 skill が読む入力として扱う。

artifact の field-level schema は task-research contract に合わせる。target object は kind、value、url を使い、val は使わない。 question_adequacy_audit.intent_policy_categories[] を使う場合は、各 category を decisions[] または source_facts[] で裏付ける。

research-workers.json の worker_count は worker_reports[] の件数と一致させる。worker_count_source: "auto_by_depth" の場合は、plan の resolved_depth の規則とも一致させる。deep では呼び出し側の AI Agent が必要な観点数を判断し、最低 3 worker にする。

artifact-manifest.json は task-research-artifact-manifest.v1、artifact-index.json は task-research-artifact-index.v1 とする。manifest は artifact_root_ref、packet_digest、issue_updated_at、issue_body_digest、artifacts[] を持ち、index は artifact_sets[] に manifest_ref と packet_digest を持つ。ref は repositories/<repo-key>/... の state-root-relative ref に限定し、GitHub 上へ /Users/... のような local absolute path を書かない。

既存 artifact を下流 skill へ渡す前の機械チェックには review-orchestrator task-research validate --packet <path> [--prior-packet <path>] [--plan <path>] [--workers <path>] [--handoff <path>] [--manifest <path>] [--index <path>] を使う。 validator は artifact shape と handoff safety だけを確認し、既存の validation、readiness、PR 前 simplify、multi-review の代替にはならない。

research artifact を下流へ渡す flow では、下流 skill の実装・起票・plan validation 前に review-orchestrator task-research grill-gate --plan <research-plan.json> --packet <research-packet.json> [--grill-mode skip] を使う。--plan は task-research の research-plan.json であり、fix-github-issue の implementation brief や implement-from-plan の plan.json ではない。deep / spike 相当の判断が残る場合は、この gate が block して /grill-me または明示 skip へ戻す。

family 全体の進捗は durable workflow state の phase、obligations、evidence、effect outcomes から再構築し、unknown や timeout を success として扱わない。

downstream use

grill-me は research-packet=<path> で task-research packet を読み、未解決質問や high-impact な chosen_by: "agent" decision を優先して interview できる。 grill-me が生成した grill-packet.json は task-research-packet.v1 互換なので、/task-research research-packet=tmp/grill-me/<id>/grill-packet.json や downstream skill の research-packet= に渡せる。

github-issue-breakdown は research=auto|off|light|standard|deep|spike と research-packet=<path> を扱い、packet から Issue draft を作る。research=off は明示 no-op として packet を作らない。

agent=claude の resume command への引き継ぎは、handoff 先の skill ごとに次のとおり。

• task-research handoff=github-issue-breakdown agent=claude のように指定した場合、agent=claude は github-issue-breakdown の起票前 validation agent selector として下流に渡す。
• task-research handoff=implement-from-plan agent=claude のように指定した場合、agent=claude は implement-from-plan の plan validation selector として下流に渡す。resume command は /implement-from-plan research-packet=... agent=claude のように、packet と validation selector を一緒に保持する。

packet を渡された下流 skill の扱いは次のとおり。

• fix-github-issue は明示された場合だけ packet を claim gate 後の read-only discovery で読み、implementation brief の evidence / decisions に反映する。
• implement-from-plan は明示された場合だけ packet から local plan draft / plan JSON を作る。

packet の facts は repo identity scoped user state root の task ledger、または legacy tmp/fix-github-issue/task-ledger-ISSUE_NUMBER.md / tmp/implement-from-plan/PLAN_ID/task-ledger.md の changed surfaces、contract sync、non-goals、acceptance、validation commands、E2E status、review scope、rerun scope へ転記できる。

どの downstream でも、research packet は validation、readiness、capability preflight、checkpoint、PR 前 simplify、multi-review の代替にならない。 task ledger も同じ gate の代替にならない。

実行例

関連

• Issue workflow skill guide
• task-research contract
• github-issue-breakdown reference
• fix-github-issue reference
• implement-from-plan reference