github-issue-validation reference
github-issue-validation は、GitHub Issue を作成する前に Issue draft や分解案を別 context / 別 Agent で検証する gate である。
strict では採用すべき指摘が残る限り Issue を作成しない。
通常経路
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> |
validation agent の設定を渡す |
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 を再実行する。
詳細 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 までの人間向け領域と、境界表示より後の AI Agent 向け領域の順序を検証する。
境界表示は Design doc の後、変更してはいけない契約 の直前に 1 回だけ必要とする。
他 project の template でも必須 field と section 名を維持し、人間向け記述が先頭側、AI Agent 向け契約が境界表示より後に置かれているか確認する。
生成時の到達形は、散文を 1 文 1 行で改行して段落を空行で分け、背景を 3〜5 文の 1 段落、要点・契約・受け入れ条件を 1 セクション 5 項目以内かつ 1 項目 1 行、要点を 2〜4 項目、design doc の連続する散文を 2 段落までかつ 1 段落 3 文以内とする。
散文段落が 300 字を超える場合と箇条書き項目が 200 字を超える場合は revise 対象にする。
障害調査の一次証跡は背景の上限から除き、受け入れ条件の 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 を残す。CLAUDE_MODEL は固定 model が必要な環境だけ渡し、未指定時は Claude CLI の default または host-local config に委ねる。