file-issue

イシューを作成する

問題が見つかったときにその場にいなかった人がイシューを読みます。多くの場合、何カ月も経ってからです。以下の各基準は、その読者が意味を尋ね直すことなく対応できるように設けられています。

1. これが1つのイシューであることを確認する

1つのイシューには、観測可能な問題が1つと、受け入れ条件が1つあります。

ブロッキング関係にある複数のチケットに分割される作業は、to-tickets に引き継ぎます。現在の会話をもとに作成した仕様は、to-spec に引き継ぎます。本当の範囲を隠すまとめチケットを作るのではなく、適切な引き継ぎ先に渡してください。

判定基準はシンプルです。範囲が1つの問題と1つの受け入れ条件に収まるか、作業を名前付きの引き継ぎ先に渡します。

2. 作成前に検索する

gh issue list --repo "$repository" --search "<the symptom in your words>" --state all --limit 20
gh issue list --repo "$repository" --search "<the symptom in the reporter's words>" --state all --limit 20

既存のチケットは、誰かが別の表現で説明して作成したものなので、異なる言葉を使って2回検索します。--state all は重要です。内容が近いクローズ済みのイシューは、再オープンすべきものか、新しいイシューに必要な背景情報のどちらかです。

作成前に、内容が近いものをすべて確認してください。それぞれについて、重複、関連、または本当に新規のいずれかに分類します。関連するものには Refs #N を付け、このイシューとの違いを1行で説明します。

判定基準は、2回とも検索を実行し、内容が近いものすべてに対処方針が決まっていることです。

3. タイトルを作成する

CLAUDE.md のイシュータイトル規則に従って、タイトルの先頭に conventional commit の種類と、作業が実際に属するモジュールを付けます。ディレクトリ名ではなく、ボード上の表記に合わせてください。

説明文は、file-pr のタイトル作成手順と同じ基準を満たしてください。疑っている仕組みではなく、観測したことを記述します。また、説明文を一般的な動詞だけで済ませてはいけません。

よいバグタイトルは、疑わしい原因ではなく、誤った挙動を示します。fix(auth): session drops on tab switch なら、原因の見立てが間違っていても問題ありません。fix(auth): cookie expiry miscalculated は、原因が別のものだと判明した時点で事実に反するタイトルになります。

判定基準は、診断結果にかかわらず真実であり続ける観測内容をタイトルに示していることです。

4. 本文を作成する

次の4つの要素をこの順番で記載し、それぞれを断片ではなく文章にします。

• 何が起きるか。 観測した挙動を記載します。本文の冒頭に置き、その前に見出しを付けません。
• 再現方法。 正確な手順、コマンド、URL、または file:line の根拠を記載します。リポジトリにアクセスできる人なら、この情報だけで同じ現象を確認できます。
• 本来どうなるべきか。 観測内容とは分けて記載します。この2つの差が、実際に求められている対応だからです。
• 完了の条件。 レビュアーが確認できる条件を1つ記載します。「正常に動作する」では条件になりません。

そのうえで、内容を伝えるために必要なものだけを追加します。具体的には、Refs #N のリンクと、必要な場合の環境情報です。環境情報は根拠から判断してください。スクリーンショットの URL バーを見れば、本番環境か開発環境かがわかります。決めつけてはいけません。

スクリーンショットは説明するのではなく、添付してください。説明だけでは、説明した人が気づかなかった情報がすべて失われます。修正する人には画像そのものが必要です。

判定基準は、4つの要素がそろっており、発生時のセッションに頼らなくても再現できることです。

5. 結果を初見で確認する

file-pr の初見確認基準を、作成したタイトルと本文に適用し、イシューに固有の次の2項目も確認します。

• 再現性。 リポジトリにアクセスできる人が、ほかの情報なしで観測内容を再現できること。
• 受け入れ。 完了条件を、作成者ではない人が確認できること。

名前を挙げていない基準は、確認していない基準です。

判定基準は、すべての基準に名前付きの確認結果があり、失敗しているものがないことです。

6. 登録する

最終的な本文をファイルに出力し、SHA-256 ダイジェストを記録します。リポジトリの安定した識別情報と最新の重複検索結果を確認してから、正確なリポジトリ、タイトル、本文のパスとダイジェスト、--label ai-created を含む作成オプション、所有権の境界、正式な読み戻しクエリを指定して preflight-mutations を呼び出します。タイトル、オプション、ラベル、本文のパス、ダイジェスト、リポジトリ、または重複検索結果が変わると、カードは無効になります。

作成前に、ai-created の来歴ラベルが存在することを確認します。このスキルを通じて登録されたすべての Issue にこのラベルを付けることで、エージェントが登録した Issue と人間が登録した Issue を区別できます。ラベルが存在しない場合は、リポジトリを指定した別個のラベル作成カードを preflight-mutations を通じて作成し、件数上限のある一覧ではなく完全一致名でラベルを検索します。作成時に許容する競合は「すでに存在する」場合だけとし、ラベルが読み戻されることを確認します。

if ! gh api "repos/$repository/labels/ai-created" >/dev/null 2>&1; then
  create_out=$(gh label create ai-created --repo "$repository" --color "A2EEEF" --description "Created by an AI agent" 2>&1) || printf '%s\n' "$create_out" | grep -qiE "already.?exists"
fi
gh api "repos/$repository/labels/ai-created" --jq .name | grep -Fqx "ai-created"

Issue の作成は共有状態に書き込みを行うため、最新の結果が ready の場合に限り続行します。タイトルは1つの引数として渡し、固定した本文はファイルで渡します。必ず来歴ラベルも指定してください。

gh issue create --repo "$repository" --title "$title" --body-file "$body_path" --label "ai-created"
gh issue view <issue-url> --repo "$repository" --json number,title,body,state,author,assignees,labels,url

担当者、見積もり、優先度を設定する場合は、CLAUDE.md に定められたプロジェクトボードの所有権の境界内に限ります。Issue を登録したからといって、これらのフィールドを設定する権限が得られるわけではありません。別のラベルを設定するために ai-created ラベルを外してはいけません。トリアージラベルはこのラベルと併せて付けます。

作成された URL が1つだけであることを確認し、取得したリポジトリ、タイトル、本文、ラベル、メタデータ、URL を承認済みペイロードと比較します。取得したラベルに ai-created が含まれていることを確認します。コマンドの結果が欠落している、または曖昧な場合は、対象リポジトリで完全一致するタイトルの候補を検索し、本文とメタデータを比較します。試行を reconcile-required として記録し、正式な検索で Issue の存在が確認されるまでは再試行しないでください。

読み戻しによって一致する Issue が1つ特定された後に限り、URL を出力します。

対象が1件の Issue であり、重複検索が両方とも実行されて解決済みで、誤った診断でも通用する観察事実をタイトルに含み、本文に4つのパートすべてが含まれ、コールドリードの基準がすべて明記されて問題がなく、正式な読み戻しで ai-created ラベル付きの出力 URL の Issue が特定されている場合に、この作業は完了です。それ以外の場合は、試行を reconcile-required のままにし、再試行しないでください。