github-issue-validation reference

github-issue-validation は、GitHub Issue を作成する前に Issue draft や分解案を別 context / 別 Agent で検証する gate である。 strict では採用すべき指摘が残る限り Issue を作成しない。

検証省略はユーザーの明示指定がある場合だけ適用する。

同じ検証対象・範囲への明示済み skip-validation は根拠を記録して再利用し、対象・範囲が変わった場合は再判断する。無回答、時間経過、permission failure を省略の許可にしない。指定対象外の required な検証・レビューや他の gate を、この指定で省略しない。

通常経路

text-file=<path> または既存 Issue を検証対象にする。
validation agent が scope、依存関係、完了条件、読みやすさを確認し、proceed|revise|stop を返す。
revise なら draft を直し、変更箇所を中心に再検証する。
strict では採用すべき指摘がなくなるまで収束させてから Issue を作成する。

代表例は /github-issue-validation text-file=tmp/issues.md agent=claude strict である。

Inputs

引数	動作
`agent=auto`	現在の runtime から validation agent を自動選択する
`agent=codex` / `agent=claude` / `agent=copilot`	validation agent を明示する
`runtime=auto` / `runtime=codex` / `runtime=claude` / `runtime=copilot`	現在 runtime の自動判定を上書きする
`config=<path>`	既存呼び出し用の設定指定。通常は省略する
`claude-mcp=off` / `claude-mcp=on`	Claude validation の MCP policy
`--claude-transport direct-pty`	Codex runtime から `agent=claude` を使う場合の direct PTY opt-in。未指定 default は headless
`repo=owner/repo` / `issue=<number-or-url>`	既存 Issue を validation 対象にする
`text-file=<path>`	Issue 化前 draft file を validation 対象にする
`strict` / `advisory`	strict は採用すべき指摘の解消を必須にし、advisory は `stop` 以外を参考扱いにできる

停止と再開

revise では Issue を作らず、Suggested Revision と findings を反映して再検証する。
stop では scope や分解方針を見直す。自動修正で起票へ進めない。
validation_environment_blocked では preflight artifact の次 action と再実行 command を確認する。
timeout や判定形式の欠落は成功扱いにしない。agent または transport の状態を直して同じ gate を再実行する。

モデルを今回だけ変更する

既定設定は自動で読み込まれる。codex-model=gpt-6-astra でモデルを、codex-effort=high で推論量を指定できる。設定ファイルの追加は不要で、指定値は子Agentと再実行にも引き継ぐ。Claude／Copilotの指定方法はモデル選択を参照。

詳細 contract

managed research / Issue creation family では、validation result は durable workflow state の obligation と evidence に投影し、最終的な resume / completion は review-orchestrator issue workflow-family-status の issue-workflow-family.v1 JSON で確認する。

manual create-effect flow で family state envelope がない場合、validation と Issue 作成後処理の完了判定は各 durable command の stdout JSON と GitHub API 確認に分ける。validation timeout、revise、stop、未検証 artifact は Issue 作成完了として扱わない。

draft file に design doc draft が含まれる場合は、Issue 本文と同じく検証対象にする。

不完全文（助詞・接続表現で途切れた行）、readability、stop-ai-slop-jp の観点を確認し、公開前に解消すべき問題を指摘する。日本語の Issue 本文と design doc draft では、stop-ai-slop-jp が追加チェックとして使われているか、または同等の観点で主体の不在、命題型見出し、壮大化、両論併記、均一すぎるリズムが解消されているかも確認する。これは AI detector ではなく、readability gate の代替でもない。

Issue 本文は issue-writing-guidelines.md を canonical source とし、Design doc までの常時表示の領域と、折りたたみの実装契約の順序を検証する。

summary 実装契約（実装者と AI Agent 向け） の <details> は Design doc の後に 1 回だけ必要とする。

受け入れ条件 は <details> 内に置き、何ができれば完了かと権限の要る手動確認は 要点 に置く。要点 のない template では、期待される挙動や解決方法など常時表示の同等の欄に置けばよい。受け入れ条件 が常時表示の領域にある draft は revise とする。

常時表示 800 字と折りたたみ 1,200 字の目安、読み替えをコメントでなく本文編集とする規則も確認する。

他 project の template でも必須 field と section 名を維持し、常時表示の記述が先頭側、受け入れ条件と実装契約が <details> 内に置かれているか確認する。

Issue draft では、変更してはいけない契約 の直後に 追加してはいけない挙動 があるかを確認する。欠落や配置違いは revise とする。

内容の具体性も検証する。non-goal / fallback の回答に沿った禁止項目を名指しし、項目がない場合は「なし」と理由を 1 行で書く。一般則だけの記述、転記漏れ、理由のない「なし」は revise とする。

生成時の到達形は、散文を 1 文 1 行で改行して段落を空行で分け、背景を 3〜5 文の 1 段落、要点・契約・受け入れ条件を 1 セクション 5 項目以内かつ 1 項目 1 行、要点を 2〜4 項目、design doc の連続する散文を 2 段落までかつ 1 段落 3 文以内とする。散文段落が 300 字を超える場合と箇条書き項目が 200 字を超える場合は revise 対象にする。障害調査の一次証跡は背景の上限から除き、受け入れ条件は「〈条件〉とき、〈観測できる挙動〉」の 1 行を 1 項目と数える。旧形式の WHEN / THE SYSTEM SHALL は 2 行で 1 項目と数える。 code block・表・引用する data 例も行数制限から除く。

検証時は、issue-writing-guidelines.md にある placeholder による架空の Issue 本文と design doc の抜粋例も、分量と構成の基準にする。これらの生成目標は readability gate の代替ではない。

複数 Issue の draft に機能依存、着手順、同一ファイル変更による merge 順序制約のいずれかがある場合は、親 Issue + sub-issue 構成でなければ revise 以上にする。分割案が委任済み・凍結済みでも、この構成違反は見逃さない。依存が 1 つもないことを draft file で確認できる場合だけ、フラット構成を許容する。

出力形式は 判定: proceed|revise|stop と、Blocking Findings、Suggested Revision、Agent-Supplied Decisions、Open Questions を維持する。

Codex runtime から agent=claude を使う場合の default は review-orchestrator claude-headless run であり、direct PTY は --claude-transport direct-pty または明示 subcommand の opt-in である。

validation の bounded wait は 10 分だが、Claude wrapper は default minimum 15 分未満の timeout を実行前に拒否する。10 分待機を使う場合は --allow-short-timeout と --short-timeout-reason "github-issue-validation bounded wait" をセットで渡し、短縮理由を artifact に残す。

Incremental Revalidation

初回 validation は full draft を渡す。2 回目以降の再検証は incremental revision を渡し、full draft 全体を毎回再送しない。

再検証ごとに validation-revision.v1 artifact を残し、前回の findings、変更した section、判断理由、full draft に戻す条件を追跡する。field-level schema は claude/skills/github-issue-validation/SKILL.md を正本とする。

全体構造、子 Issue の数、依存関係、scope 境界、公開 API / 設定形式 / データ形式の前提、または validation target 自体が変わった場合は mode=full_draft に戻す。

incremental revision は strict validation gate を弱めるものではない。proceed でも採用すべき指摘が残る場合は再修正し、最大 10 回の validation loop 内で収束させる。

Environment Gate

validation agent を起動する前に、作業ディレクトリへの write、prompt stdin、必要な GitHub API、external agent command を preflight する。preflight failure は validation_environment_blocked として扱い、Issue 作成や post-create へ進まない。

Codex runtime で agent=claude を使う場合、review-orchestrator claude-headless run は transport 起動前に --prompt-path、--output-path の親 directory、--repo-path、Claude command、model / effort 設定を確認する。失敗時は claude-headless-preflight-result.v1 の JSON に分類、失敗 path または command、次 action、再実行 command を残す。model / effort は review-orchestrator agent-runtime resolve-models が自動解決し、cli_args を既存 transport へ渡す。

github-issue-breakdown reference

この repo の example config は Claude Opus 5.5 / medium、Codex GPT-6.1 Sol / medium を初期値とする。用途別 subagent の独立設定はモデル選択契約を参照する。明示 override と resume 時の保持は従来どおり。