github-issue-breakdown reference

要求を GitHub Issue に分け、起票前の確認から Issue 作成まで進めたい利用者向けの入口である。

対象読者と使いどころ

既定では Issue 作成までで止まり、コード編集や PR 作成は行わない。

まず何が起きるか

1. 要求と repository の一次情報を確認し、必要なら read-only research を行う。
2. high-impact な未確定事項をユーザーに確認してから Issue draft を作る。
3. draft を起票前 validation に渡し、採用すべき指摘を反映する。
4. Issue を作成し、Type、Project、親子 link、親 Issue 本文を整える。
5. fix / continue-to-fix / implement がある場合だけ、first fix target 1 件を実装 workflow へ渡す。

停止条件

• high-impact な判断が未確定なら Issue を作成しない。validation を実行した場合も、判定が proceed になるまで止める。skip-validation の明示時は validation を省略する。
• Issue 作成結果が不明な場合は再投稿せず、作成済みかどうかを照合する。
• first fix target が複数または不明な場合は、実装へ進まず人間の選択を待つ。
• Cosense project、公開設定、authoring 記録を確認できない場合は design doc を公開しない。

詳細 contract

github-issue-breakdown は、要求を GitHub Issue として実装可能な粒度へ整理して起票する入口である。 breakdown が 2 件以上の Issue になり、機能依存、着手順、同一ファイル変更による merge 順序制約のいずれかがある場合は、親 Issue + sub-issue 構成にする。依存が 1 つもないことを draft file に記録した場合だけ、独立した複数 Issue のフラット起票を許容する。

既定では Issue 作成、作成後処理、必要な sub-issue link、親 Issue 本文更新までで止まり、実装へは進まない。実装へ続ける場合だけ fix / continue-to-fix / implement を明示し、breakdown-to-fix contract で選ばれた first fix target 1 件を fix-github-issue に渡す。

Issue と design doc の三層構造

大きな変更は Issue / Cosense design doc / tasks の三層で作る。ただし design doc 層は design-doc の作成判定で作る場合だけ置き、作らない場合は Issue（+ 子 Issue）と省略理由で構成する。

Issue 本文は目的、変更してはいけない契約、受け入れ条件、Validation command、design doc link または省略理由に限定し、実装イメージは repository owner に対応する Cosense project、1 Issue / 1 PR の実装単位は子 Issue に置く。

design doc は作成時点のスナップショットとし、進捗と PR は GitHub Issue 側を source of truth とする。

AI Agent の書き込み先は loilo-inc -> loilo-dev、TomoakiMizuno -> mizuno-dev で、map と違う project は hook で block する。loilo は人間が書いた従来資料の読み取り専用 project とする。

Issue 本文の表現規約

Issue 本文は、Design doc までの人間向け領域を先に置き、境界表示より後に AI Agent 向け領域を置く。 親 Issue だけが持つ追跡情報（Sub-issues・実装順序と並列性）も、人間向け領域の Design doc より前に置く。 Design doc は人間が参照する資料への link または省略理由として扱い、その直後、変更してはいけない契約 の直前に水平線と「ここからは AI Agent 向けです。」の境界表示を 1 回だけ置く。 任意の実装契約、実装イメージ、依存と merge 順序も AI Agent 向け領域に含め、人間向け領域へ新しい section は追加しない。

AI Agent 向け契約に置く値・規則については、人間向け領域には決定とその理由だけを書く。契約へ一本化した内容を散文で再掲しない。

stacked 依存を意図する場合も verifier の受理文法は変えず、既存の順序表の後に main path と PR chain を prose で書く。

| Phase | Issue | 内容 | 並列可否 | 依存 |
|---|---|---|---|---|
| 1 | #10 | 基盤の追加 | 開始可能 | なし |
| 2 | #11 | 基盤を使う機能 | 不可 | #10 |

最短で進める main path は #10 → #11 とする。
並列候補はなく、#11 は #10 の完了後に着手する。
#11 は #10 の PR chain に積む (stacked)。

---

> [!NOTE]
> **ここからは AI Agent 向けです。**
>
> 以下は実装時に守る契約、受け入れ条件、検証方法です。

他 project の Issue template を使う場合も必須 field と section 名を維持し、概要・背景・再現手順・Design doc などを先頭側、実装契約・受け入れ条件・検証 command などを境界表示より後に配置する。

Issue 本文の最小構造は、次の表現規約に従う。

• 逆ピラミッドで結論を先に置く。
• 散文と箇条書きの使い分けでは、因果・判断理由は散文、列挙は箇条書きにする。同じ主語・同じ軸の事実が 3 件以上並ぶ場合は、表または箇条書きへ変換する。
• 説明的見出しを使い、長い付随情報は <details> で折りたたむ。
• 子 Issue の依存関係など tasks 層の追跡に限った図（Mermaid）を使い、実装設計の詳細図は design doc 側に置く。
• 外部根拠に基づく主張には出典 link を付ける。

生成目標は、散文を 1 文 1 行で改行して段落を空行で分け、背景を 3〜5 文の 1 段落、要点・契約・受け入れ条件を 1 セクション 5 項目以内かつ 1 項目 1 行、要点を 2〜4 項目、design doc の連続する散文を 2 段落までかつ 1 段落 3 文以内とする。 Issue 本文の連続する散文段落も 2 つまでとし、超える説明は箇条書き、表、図、code block へ変換する。この上限は、解決方針など他 project template 由来の自由散文 section にも適用する。 散文段落が 300 字を超える場合と箇条書き項目が 200 字を超える場合は revise 対象にする。 障害調査の一次証跡は背景の上限から除き、受け入れ条件の WHEN / THE SYSTEM SHALL は 2 行で 1 項目と数える。 code block・表・引用する data 例も行数制限から除く。 canonical guideline には、placeholder による架空の Issue 本文と design doc の抜粋例も載せる。

共通 readability gate は Issue 本文、PR 本文、design doc 本文を対象とし、次の不足を reject / revise 観点に含める。

• 出典不足: 外部根拠に基づく主張に検証可能な出典 link がない。
• 構造変換不足: 列挙・比較できる内容が散文の羅列になっている。
• Issue 本文の層間重複: 人間向け領域が AI Agent 向け契約の値・規則を言い換えている。この観点は Issue 本文だけに適用する。

生成目標、抜粋例、表現規約、readability gate は claude/skills/github-issue-breakdown/references/issue-writing-guidelines.md を source of truth とする。

design doc の作成判定と表記規約

design doc は design-doc=auto|on|off option（default auto）の作成判定に従い、実装者に渡す価値がある時だけ作る。auto の作成条件を満たさない場合と迷う場合は作成せず、判定根拠を Issue の Design doc section に省略理由として書く。親子 Issue でも省略できる。

auto で省略する場合は、auto の各作成条件を満たすかを省略理由に書く。「1 Issue・1 PR で完結するため」など、作成条件にない軸だけでは省略理由にできない。

後続の low tier worker に必要な candidate_files、fenced code block を含む implementation_sketch、validation_commands は current research packet に置き、これらの粒度要件だけで design doc を作らない。page を省略しても low tier の dispatch 条件は緩和しない。

design doc の図表選択、fallback、公開後の確認は $cosense-visual-authoring に委譲する。詳細な作成判定と design doc 本文の原則は claude/skills/github-issue-breakdown/references/issue-writing-guidelines.md を source of truth とする。

design doc の依頼・レビュー者 icon は、settings page の作成者など他情報源から推測せず、cosense whoami <origin> が返す PAT ユーザーの name field を member icon 記法（例: name: mizuno → [mizuno.icon]）へ変換する。

design doc 本文で子 Issue に言及する時は、実 Issue 番号と GitHub Issue URL を含む外部 link 記法（例: [Issue 1557 https://github.com/TomoakiMizuno/agent-dotfiles/issues/1557]）で書き、「子N」のような相対 label や link を伴わない番号だけの記載は使わない。

Issue 作成後の design doc 更新検査では、placeholder 残存、相対 label 残存、子 Issue 実番号の言及ごとの GitHub link の 3 点を確認する。これらの規則と検査観点は issue-writing-guidelines.md と references/draft-validation.md を source of truth とする。

local draft の検査と早見表としての扱い

Issue 本文の構造検査には review-orchestrator --repo <owner>/<repo> issue inspect-body --body-file <draft-path> を使う。次の状態を report-only で観測し、観測があっても exit code は 0 のままとする。

• 300 字を超える散文段落: issue_paragraph_too_long
• 200 字を超える箇条書き項目: issue_list_item_too_long
• 人間向け領域より前に置かれた Agent 向け section: issue_layer_order
• 3 つ以上連続する散文段落: issue_prose_run_too_long
• 800 字を超える section 内の散文合計: issue_section_prose_too_long

design doc の構造検査には review-orchestrator design-doc lint --file <draft-path> [–mode report_only|required] を使える。--file - は stdin を読み、既定の report_only は finding を観測結果として exit code 0 で返す。required は error finding がある場合だけ exit code 2 を返し、入力 file や引数のエラーは exit code 1 である。

検査対象は placeholder、相対 label、GitHub Issue link を伴わない Issue 番号、要点の GitHub Issue / repository link 欠落、code: / table: ブロックを分断する非インデント空行（broken_code_block）、100 字を超える散文行（prose_line_too_long）である。prose_line_too_long は required mode でも公開を止めない。一般的な自然文品質や公開済み page は対象にしない。

詳細な orchestration 手順は breakdown-to-fix contract、claude/skills/github-issue-breakdown/SKILL.md、claude/skills/github-issue-breakdown/references/ を source of truth とし、この文書は利用者向けの引数早見表として扱う。

Durable workflow と復旧

durable effect と recovery state

Issue 作成は durable effect として実行され、GitHub create の結果が不明な場合は同じ本文を自動で再投稿しない。作成済み Issue を確認して手動 bind するか、作成されていないことを確認してから recovery する。

workflow recovery state は local file store を正本とし、exact-key lookup と versioned compare-and-set は既存の workflowstate.Store.Load / Append(expectedRevision) を使う。Issue create / post-create の effect idempotency record は既存の EffectStore を使い、workflow recovery state の revision 管理とは混ぜない。

family workflow の phase 管理

managed workflow として開始した research / Issue creation family 全体の resume と完了判定は、各 durable effect command に --state-workflow-kind / --state-workflow-id と必要な --state-evidence を渡して family state を更新し、review-orchestrator issue workflow-family-status --workflow-kind <kind> --workflow-id <id> の issue-workflow-family.v1 JSON projection で確認する。

design doc を公開した flow は、repo-scoped github-issue-breakdown-issue-binding.v1 を issue create-effect --state-design-doc-authoring <path> に渡す。gate mode は –state-design-doc-authoring-mode report_only|required で、既定は report_only である。command は GitHub dispatch 前に record の schema、repository、workflow、page identity を検査し、作成成功後に Issue identity を issue と linked_issues へ追記する。

report_only は missing、invalid、ambiguous、unknown を観測し、Issue 作成と family completion を止めない。required は dispatch 前の不整合を拒否し、作成後の binding または state 更新が失敗した場合は作成済み Issue を保持して reconcile_design_doc_authoring を返す。published family の completion では design_doc_authoring_record_valid を要求する。approved skip と、design doc status を持たない既存 family は not_enrolled/report_only として扱う。

この projection は phase、remaining obligations、accepted evidence、effect outcomes を program side で評価し、unknown effect、validation revise、unverified handoff、stale evidence を success に丸めない。

同じ時点の完了判定で複数の独立 gate を確認する場合は、既存 command を同じ shell request で実行し、各 stdout schema の terminal field を一括評価する。create、post-create、link、parent finalization は前段の effect 結果で後段の引数が決まるため、この一括確認には含めない。

manual create-effect flow で family state envelope がない場合、workflow-family-status が next_required_action: "select_completion_source" を返すことがある。これは Issue 作成失敗ではない。manual flow の完了判定は create-effect / post-create / link-sub-issue / finalize-parent-body の stdout JSON と GitHub API 確認を source of truth にする。

validation evidence の --state-evidence には、github-issue-validation 配下の artifact、validation-result.json / issue-validation-result.json、または 01-validation-result.md のような番号付き Markdown artifact を渡す。

family phase は initialized、research_planned、research_running、research_ready、waiting_intent_policy_input、drafting、validation_pending、validation_revise、ready_to_create、creating_issues、post_create、linking_sub_issues、finalizing_parent、completed、blocked、failed を使う。

単一 Issue の managed flow は post-create に --state-family single を渡すと、post-create 成功で family state を phase=completed / status=completed に到達させ、workflow-family-status が proceed を返す。

親子 Issue flow(宣言なし、または --state-family parent)は従来どおり post_create → linking_sub_issues → finalizing_parent → completed の遷移と、sub_issues_linked / parent_body_finalized obligation・link-sub-issue / finalize-parent-body effect の要求を維持する。

completion obligations と budget policy

completion obligations は research_packet_valid when research_depth is not off、intent_policy_resolved、validation_proceed、issue_create_reconciled、post_create_complete、sub_issues_linked、parent_body_finalized、handoff_artifact_valid when handoff is requested、skipped / unknown / validation timeout are not successful completion evidence として追跡する。

budget / effect policy は projection is read-only and does not run agents or external mutation、state stores artifact refs and status, not prompt or diff bodies、IssueCreateStatusUnknown requires reconcile_effects、EffectStore outcomes are evaluated separately from workflowstate revision、GitHub mutation results are program-side evidence, not Agent natural-language claims として扱う。

recovery operations には request_intent_policy_input、revise_validation、revise_workflow_state、reconcile_effects、refresh_evidence、resolve_obligations、manual_recovery、select_completion_source を含める。

GitHub Issue への metadata 非埋め込みと replica 方針

GitHub Issue 本文・コメント・ラベル・添付には、個人用 workflow metadata や hidden correlation marker を既定では埋め込まない。この除外対象は skill 内部のオーケストレーション状態であり、調査対象システムの実行 URL、ログ URL、出力パス、関連 ID など、再現や確認に必要な一次証跡は含まない。

private remote store を使う場合も optional recovery replica であり、GitHub Issue や replica を source of truth にしない。replica の欠落、古さ、provider mismatch、不一致、破損、読み取り失敗、schema / consistency error は fail-closed とし、local authoritative state が信頼できる状態に戻るまで再作成や recovery を進めない。

research=... は Issue draft を作る前の調査深度、agent= は起票前 validation の実行 Agent、agents= は後続実装へ渡す local reviewer selector、reviewers= は GitHub reviewer / trigger selector であり、それぞれ役割が違う。

router structure

claude/skills/github-issue-breakdown/SKILL.md は入口 context を小さく保つ router である。

inventory、draft / validation / create flow、sub-issue command details、breakdown-to-fix handoff、final boundary の詳細 contract は claude/skills/github-issue-breakdown/references/ の phase-specific reference に分け、実行時は必要な phase だけ読む。

public contract を変更する場合は router と references の両方を source of truth として扱い、internal/skilldocs の tracked contract も更新する。

Issue 作成と検証

agent= は起票前 validation の selector であり、実装後の reviewer を選ぶ agents= や reviewers= とは別物である。

Issue 作成だけで止める場合、pr=、review=、e2e=、agents=、reviewers=、max-local-review-loops=、max-github-review-loops=、worktree= は後続実装へ渡されない。

Copilot validation を使う場合

/github-issue-breakdown agent=copilot は、Issue draft の起票前 validation を Copilot CLI に依頼する指定である。agent=copilot は起票前 validation agent selector であり、実装後 reviewer selector の agents=copilot とは別物として扱う。

Issue 作成だけを求めた場合は validation、post-create、必要な sub-issue link、親 Issue 本文更新までで止まり、review / E2E / 実装 handoff は走らない。

Copilot CLI validation は prompt file のある directory だけを --add-dir で許可し、shell / write tool を使わない read-only validation として扱う。この境界は github-issue-validation reference と claude/skills/github-issue-validation/references/ を source of truth とし、github-issue-breakdown 側では利用者が選ぶ入口と停止条件だけを説明する。

起票前 validation の判定は次のとおり。

• strict mode で proceed 以外になった場合、または proceed でも採用すべき指摘が残る場合は Issue 作成へ進まない。
• timeout、invalid_output、subagent_unavailable、cleanup_failure は validation 未完了であり、Issue 作成へ進まず再実行、修正、中止、またはユーザーの明示確認へ戻る。
• skip-validation はユーザー明示の override であり、起票前 validation だけを省略する。Issue 作成後処理、sub-issue link、親 Issue 本文更新の責務は省略しない。

Issue 作成後は review-orchestrator issue post-create で Issue Type と Project inbox を整える。Issue 作成の結果が unknown の場合は、manual bind または confirmed_not_created の recovery が終わるまで post-create、sub-issue link、親 Issue 更新へ進まない。

workflow-id と effect-key は idempotency scope なので、同じ key で別 run の過去 Issue が返った場合は、返却 JSON と GitHub 上の Issue を確認して衝突として扱う。再実行で新規作成が必要なら、run 固有の workflow-id または新しい dispatch generation の effect-key を使う。

sub-issue link は review-orchestrator issue link-sub-issue --parent <parent> --child <child> を使い、raw gh api を手順の source of truth にしない。同一 repository の child は番号または URL、same-owner cross-repo の child は canonical Issue URL を渡す。command は child repository から REST ID を取得して parent repository へ link し、different-owner は mutation 前に拒否する。完了済み effect の replay では外部 mutation を繰り返さない。

単一 Issue、独立した複数 Issue、親子 Issue の各本文は、issue create-effect の直前に review-orchestrator prose-lint --file <body-file> と review-orchestrator --repo <owner>/<repo> issue inspect-body --body-file <body-file> で観測する。子 Issue ごとに別 artifact を残し、親 Issue の最終本文も issue finalize-parent-body の直前に再度観測する。

artifact 名には対象種別、対象識別子、検査段階、run 固有値、単調増加する attempt 番号を含め、既存 file を上書きしない。issue inspect-body に観測があれば本文を最大 3 回作り直す。観測が残った場合も Issue 作成・更新を止めず、同じ対象、検査段階、run 固有値のうち attempt 番号が最大の artifact を最終観測として残す。

design doc の prose_line_too_long も最大 3 回の作り直し対象とする。観測が残った場合は最後の JSON を保存して公開を続ける。prose-lint-observation.v1 の観測または non-zero exit も既存どおり Issue 作成・更新を止めず、失敗と artifact path を報告する。

issue create-effect と issue finalize-parent-body は本文検査の後、GitHub へ送る本文、final body hash、更新後の照合に使う本文へ AI attribution フッターを自動付与する。呼び出し側でフッターを手動追加する必要はなく、既存の正規フッターは実行 runtime の 1 block に置き換わる。--base-body-file の並行編集検出はフッターを除いた本文で比較するため、フッターの有無だけの差分を他者編集として扱わない。

親 Issue 本文の最終更新は review-orchestrator issue finalize-parent-body で durable effect として実行する。更新前に生成済み本文を検証し、base body snapshot または sha256 で並行編集を検出し、更新後の GitHub 本文を smoke verification する。既に同じ final body が反映済みなら replay success とし、GitHub 上の body が base と異なる場合は上書きせず manual resolution に止める。

子 Issue 作成後の final body では、同一 repository の child を、Mermaid 以外の Sub-issues、順序 table の Issue / 依存 / 並列可否、main path、parallel prose で GitHub autolink が有効な bare #N として表す。inline code、fenced code、HTML の code element、escape、Markdown link で囲んだ同一 repository の参照は verification failure とする。Mermaid の可視 label は autolink 検査の対象外とする。same-owner cross-repo の child は、Mermaid では owner/repo#N の plain text、それ以外の各 surface では owner/repo#N を label、canonical Issue URL を遷移先にした Markdown link にする。親 Issue node の可視 label には親番号を入れず、draft placeholder の #<child-a>、child-a、TBD は残さない。

manual_resolution が返った場合は、GitHub 上の current body と stdout JSON の current_body_sha256 を確認し、intended final body が issue verify-parent-body --body-file で成功する場合だけ、確認済み SHA として --base-body-sha256 <current_body_sha256> を渡して再実行できる。current body が想定外、または final body verification が fail する場合は、本文を再生成してから durable update に戻る。

Issue draft を作る前に、intent-policy inventory で Agent が補う解釈・選択を棚卸しする。対象は UX 可視挙動、データ形式、公開 API、設定形式、scope / repo 境界、Issue 分割、non-goal、fallback、validation 範囲を含む。

ローカル一次情報で解消できる fact-check を先に潰す。high-impact 未確定が 1 件でも残る場合は、AskUserQuestion で推奨案を最初に示して確認する。

各質問には「この回答で Issue 構成のどこが変わるか」を添える。high-impact 質問には grouped questions の最大 3 個制限を適用しない。high-impact ではない確認事項が 4 件以上ある場合だけ、最大 3 個の grouped questions に束ねる。

この inventory interview は起票前の最小確認である。grill-me はユーザーが明示して起動する深掘り interview であり、自動では起動しない。

AskUserQuestion が使えない runtime は質問一覧を報告して draft 前に停止する。questions=off がない限り、Agent 補完で Issue 作成へ進まない。

実装イメージは Issue 本文へ詰め込まず linked Cosense design doc に置く。page を作る前に owner / project map を解決し、cosense browsePage https://scrapbox.io/<resolved-project>/settings で現在の表示設定と commitId を取得する。

settings URL、commitId、使用する装飾は local workflow artifact に記録して後続 Agent が再確認できるようにし、page 本文には置かない。

settings に定義された見出し、囲み、marker、表、画像の記法を使い、最初の画面に結論、変更してはいけない契約、Issue / tasks との関係を出す。散文が生成目標を超える場合は、箇条書き、表、図、code block へ分ける。

図表の選択、fallback、submit 後の browser 確認は $cosense-visual-authoring に従う。

期待する関数シグネチャまたは変更前後の擬似コード、入出力データ例など、契約 section に置けない実装イメージを含める。これらを渡す必要がない場合は、design-doc=auto の作成判定を作らない側へ見直す。該当のない section は削り、固定 template を機械的に複製しない。

公開時は、起票前 validation を実行した場合は proceed になった後、skip-validation が明示された場合は validation を省略したまま、review-orchestrator design-doc lint --file <draft-path> --mode report_only を実行する。stdout JSON は local workflow artifact の作業ディレクトリへ保存する。validation を実行した場合は validation artifact と同じ作業ディレクトリを使い、skip-validation の場合も lint artifact 用に同じ directory を用意する。

report_only の finding は flow を止めないが、lint の実行または artifact 記録に失敗した場合は公開しない。validation が revise / stop の場合も previewEdit / submitEdit へ進まない。

lint artifact を記録できたら、ユーザーの書き込み許可を確認し、$cosense skill の edit-page workflow に従う。対象 page と近接 page を確認してから、同じ resolved project URL で cosense previewEdit --new と cosense submitEdit <projectUrl> <previewId> を実行する。submit が返した実 URL を Issue に入れ、cosense browsePage で本文と link 接続を確認する。

応答が曖昧な場合は再送前に対象 page を読み、preview だけ、project mismatch、認証 error、または submit 結果不明の状態を公開済みとして扱わない。

Issue 本文を shell 展開経由で投入する場合だけ、inline code は <code>...</code>、fenced code block は ~~~ を使う。--body-file で literal file を渡す場合は、通常の backtick / triple backtick を使ってよい。

日本語の Issue 本文または design doc 本文を作成・大幅更新した場合は、公開前に stop-ai-slop-jp を追加で使う。これは最小構造、readability gate、validation gate の代替ではない。

ユーザー回答済み前提や一次情報で凍結した判断は draft file または validation input に保持し、後段 validation が同じ前提を再利用できるようにする。

validation 後の Open Questions は、local fact-check、初期回答または一次情報で凍結済み、既存回答や一次情報を覆す根本変更に分類する。追加質問に戻るのは根本変更だけで、wording 修正、scope tightening、validation target の明確化、回答済み前提の本文反映では戻らない。

初回 validation は full draft を text-file=<draft-file> で渡し、2 回目以降は incremental revision を text-file=<revision-input-file> で渡す。

validation-revision.v1 artifact には mode、attempt、previous_findings、changed_sections、decision_log、full_revalidation_triggers、full_revalidation_required、validation_input_summary を残す。全体構造、子 Issue の数、依存関係、scope 境界、公開 API / 設定形式 / データ形式の前提、validation target が変わった場合は full draft に戻す。

research packet

既定の research 深度と packet の役割

github-issue-breakdown の Issue 化前 flow では research=auto が default である。research packet は、Issue draft の背景、判断、候補ファイル、未解決質問を補う調査メモである。

この skill の read-only discovery 内で task-research contract に従い、research-plan.json、research-packet.json、research-brief.md の結果を Issue draft の背景、判断表、Mermaid、擬似コード、Rules / Examples / Questions に反映する。

research=off は明示 no-op とする。

既存 packet の指定と検証

research-packet=<path> を指定した場合は、既存 packet の source_facts、candidate_files、existing_contracts、recommended_approach、alternatives、implementation_sketch、unresolved_questions、validation_commands を読む。

research-packet=auto を指定した場合は、Issue draft 作成前に明示 target digest で review-orchestrator task-research discover --target <normalized target> --repo <owner/repo> を実行し、candidate_state=single かつ唯一の候補が candidate_status=current の時だけ採用する。candidate_state=none は packet なし通常 flow、ambiguous / stale_or_invalid_only は自動採用せず停止する。

既存 packet を読む場合、または research-packet=auto で採用した packet を読む場合は、Issue draft 作成前に review-orchestrator task-research validate --packet <path> を通す。

packet に chosen_by: "user" の decision がある場合は、Issue draft の判断表や前提に同じ判断を chosen_by: "user" の前提として反映し、起票前 validation input から落とさない。

grill gate と未確定判断の解消

research artifact を持つ flow では Issue draft 作成前に review-orchestrator task-research grill-gate --plan <research-plan.json> --packet <research-packet.json> [--grill-mode skip] を通す。blocked の場合は /grill-me で未確定判断を解消するか、grill=skip を明示するまで Issue 作成へ進まない。inconclusive の場合は packet / plan の不足または読み取り不能を直す。

question_adequacy_audit.passed=false や resolved_depth=spike が残る場合は、Issue 作成へ進まず質問または spike に戻る。

research packet に high-impact 未確定が残る場合も、起票前の最小 interview で確認する。回答は質問、回答、確認日とともに draft file または validation input の decision evidence に残し、chosen_by: "user" として扱う。

grill-me は深掘りが必要な時にユーザーが明示して起動する。直接確認後も task-research validate、grill gate、起票前 validation は必要に応じて再実行する。

packet の記録範囲と代替できないもの

明示 packet を使って Issue を作成した場合は、作成された issue number / URL と packet manifest の binding を local workflow state または artifact に記録する。GitHub Issue body / comment / label には local state key、hidden marker、local absolute path を書かない。

research packet は github-issue-validation、post-create、sub-issue link、breakdown-to-fix handoff の代替ではない。

実装へ続ける指定

実装移行が明示された場合だけ review-orchestrator issue breakdown-to-fix を呼ぶ。親 Issue や複数候補をそのまま fix-github-issue へ渡さず、artifact の first_fix_target が 1 件に決まった場合だけ実装へ進む。needs_human_selection や stop が返った場合は、推測で実装を始めない。

選択対象が cross-repo、または同番号の child が複数 repository にある場合、handoff は停止する。cross-repo child は fix-github-issue --issue <canonical Issue URL> で child repository の workflow として直接開始する。

PR handoff

pr=draft|create|none は fix / continue-to-fix / implement と同時に指定された場合だけ有効で、stdout JSON、handoff.json、checkpoints[]、resume_command に pr_mode として保持する。Issue 作成だけで止める呼び出しに pr= が付いた場合は、消費先のない実装移行 option として停止する。

review handoff

review handoff で許可される組み合わせと停止条件は次のとおり。

• github-issue-breakdown の handoff option として許可される review mode は review=auto|simplify|once|on だけである。
• review=off、no-review、multi-review alias は handoff では使わず、必要な mode を明示する。
• review=simplify / review=once と、review=auto / review=on 用の agents=<runtime> / reviewers= / loop budget を同時に指定した場合は停止する。ただし review=simplify agents=none は冗長な skip 指定として許可される。
• agents= の正規化は handoff 先の fix-github-issue と同じ規則に従う。空要素は読み飛ばし、重複した runtime、none と他 runtime の併記、正規化後に有効な runtime が 1 件も残らない指定は停止する。
• review=once agents=none は one-shot reviewer selector と矛盾するため停止する。

E2E handoff

Issue 作成だけで止める場合は E2E を実行しない。未解決の auto を e2e_mode として扱わず、successful auto plan の resolved_e2e_mode だけを後続 gate に渡す。

worktree handoff

worktree=on|off は fix / continue-to-fix / implement と同時に指定された場合だけ有効で、stdout JSON、handoff.json、checkpoints[]、resume_command に worktree_mode として保持する。Issue 作成だけで止める呼び出しに worktree=on|off が付いた場合は、消費先のない実装移行 option として停止する。

停止する代表例

実行例

関連

• Issue workflow skill guide
• task-research reference
• task-research contract
• breakdown-to-fix contract
• implementation readiness contract
• E2E auto policy contract
• review operations