oh-my-issues

oh-my-issues

イシューバックログをロードマップに変換します。Issue は作業単位ではなく、症状を示すデータです。作業単位となるのは、それらを引き起こすアーキテクチャ上の欠陥です。最終的な状態は open issues == open plans、つまり 1 対 1 です。

基本原則

Issue を 1 件ずつクローズするのはやめましょう。共通のアーキテクチャ修正で解決できる症状をクラスターにまとめ、各クラスターに正規の置き場所（plan マスター Issue と plans/0X-*.md の設計ドキュメント）を 1 つ用意します。すべての子 Issue を標準化された誘導コメントとともにクローズし、各クラスターにつき 1 つの PR で、すべての子 Issue をまとめてクローズします。新たに報告されたバグは、新しい追跡対象 Issue として起票するのではなく、該当するマスターに「Round N」コメントとして追加します。

このアプローチは、3 つの面で効果を積み重ねます。アーキテクチャ修正によって症状の一群をまとめて解消でき、計画のテストマトリックスによって予防策を CI に定着させられ、標準化されたトリアージによって残る流入にも低コストで対応できます。

使用する場合

• リポジトリに未クローズの Issue が 20 件以上あり、多くが重複、または同じ欠陥のプラットフォーム固有の症状に見える場合。
• ユーザーが Issue 一覧の「トリアージ」「統合」「クラスター化」「重複排除」「グループ化」または「計画の作成」を求めている場合。
• 新しいバグが報告され、既存の作業に含めるべきかユーザーが判断したい場合。
• 関連する Issue のクラスターを解決する、対象を絞った PR を出したい場合。

使用しない場合

• 未クローズの Issue が約 15 件未満の場合：単にクローズしてください。
• Issue が実際に独立しており、共通する根本原因がない場合：Issue ごとに修正するのが適切です。
• リポジトリに plans/ の運用ルールがなく、ユーザーも導入を望んでいない場合：まず提案し、押し付けないでください。

3 つのモード

モード 1：クラスター化の一括実施（初回の削減）

バックログがまだ一度も統合されていない場合に使用します。目標は、N 件の Issue を 1 回の作業で N_plans 件のマスターに整理することです。

1. すべてを全文で読みます。 未クローズの各 Issue の本文 と コメントスレッドを取得します。タイトルだけでは不十分です。全文を確認しなければ、表面的なグループ化になってしまいます。再現手順、リンクされた重複 Issue、診断出力は、元の本文ではなくコメントに記載されていることもよくあります。正しいページネーション付き一覧取得と Issue ごとのコメント取得については、下記の「GitHub CLI の基本コマンド」を参照してください。gh issue list を 1 回実行しても、コメント本文は返されません。
2. 表面的な特徴ではなく、根本原因でクラスター化します。 クラスター化の判断基準は「1 つのアーキテクチャ変更ですべて解消できるか」であり、「同じ単語が出てくるか」ではありません。「Windows」は表面的な特徴であり、「ホストシェルによる spawn 契約の違反」は根本原因です。表面的な特徴が異なる 2 つの Issue でも、同じクラスターにまとめられます（たとえば、2 つの異なるコードパスで発生している環境変数の漏えいが、共通する環境分離境界の欠如に起因する場合）。
3. 各クラスターにアーキテクチャ上の問題を表す名前を付けます。 タイトルの形式は [plan-XX] <Architectural Defect> — <one-line scope> です。例：[plan-02] Spawn-Contract Templating — canonical ${CLAUDE_PLUGIN_ROOT} resolution across all hosts。タイトルから修正内容が伝わるようにし、単なるトピック名にしないでください。
4. 各クラスターにつきマスター Issue を 1 つ作成します。 本文には、アーキテクチャ上の欠陥、子 Issue（Issue 番号を記載）、修正手順、再発防止に必要なテストマトリックス（ホスト × IDE × シェルなど）を記載します。
5. 各マスターに対応する plans/0X-<slug>.md をリポジトリ内に作成します。 Issue は公開用の追跡場所、ドキュメントは設計です。互いに参照させてください。
6. 標準化された誘導コメント（下記参照）を付け、すべての子 Issue をクローズします。 あわせて not planned を設定します。
7. 最終状態を確認します。 gh issue list --state open の結果がマスターだけで、それ以外は含まれていないことを確認します。

約 100 件の Issue で目指す形は、4～8 件のマスターです。10 件を超える場合は、表面的な特徴でクラスター化している可能性があります。3 件未満の場合は、各クラスターを 1 つの PR でリリースするには範囲が広すぎる可能性があります。

モード 2：トリアージ（新規に届いたバグ、定常状態）

統合が完了した後に新しいイシューが登録された場合に使用します。目標は、イシュー一覧が再び膨れ上がらないようにすることです。

1. 新しいイシューの本文を最後まで読みます。
2. 症状を既存の計画マスターと照合します。 オープン中の各マスターについて、次のように確認します。ここに記載された修正で、この新しいバグも修正されるか？ そうであれば、その計画に含めます。
3. 該当するものがある場合、マスターに「Round N」コメントを投稿し、次の内容を含めます。
   • 新しい子イシューの番号
   • 症状の簡潔な説明
   • 具体的な修正の概要（1～3 行。例：「case "$_SH" in /*.exe|"") _SH=bash ;; esac でガードする」）
   • バグによって明らかになった新しいテストマトリックスの項目
4. 標準の誘導コメントを付けて子イシューをクローズし、not planned にします。
5. 該当するものがなく、バグが本当に新規のものである場合は、新しい計画マスターと plans/0X-*.md を作成します。これは避けてください。ほとんどのバグは既存の計画の子イシューです。

モード 3：バンドル（クラスターをリリースする）

計画のスライスをリリースできる状態になった場合に使用します。目標は、1 つの PR で N 個の子イシューをまとめてクローズすることです。

1. マスターの子イシューを一覧表示します。 マスターの本文と統合コメントから、この計画に割り当てられたすべての子イシュー番号を集めます。
2. 各子イシューの症状が、PR のアーキテクチャ上の修正でカバーされることを確認します。 カバーされない子イシューがある場合、PR はまだ準備できていないか、その子イシューは別の計画に属しています。
3. PR の説明を作成します。 タイトルには計画のスライスを記載します（例：「fix(spawn): canonical ${CLAUDE_PLUGIN_ROOT} resolution」）。本文には、GitHub がマージ時に自動クローズできるよう、すべての子イシューを Closes #N の形式で記載します。
4. 計画のテストマトリックスを同じ PR で CI に追加します。 マトリックスがないと、クラスターが再発します。
5. マージ後、すべての子イシューがカバーされている場合に限り、マスターイシューをクローズできます。計画に残りの作業がある場合は、マスターをオープンのままにして、部分リリースのチェックポイントとして PR へのリンクを追加します。

計画マスターの命名

計画マスターのタイトルには、修正内容を明示する必要があります。

悪い例（表面的）	良い例（アーキテクチャ上の内容）
Windows のバグ	ホスト間の Spawn-Contract テンプレート化
ワーカーのクラッシュ	ワーカー／デーモンのライフサイクル強化 — 監視、ヘルスチェック、再試行
認証の問題	ワーカー環境の分離 — SDK サブプロセスからホスト CLI 環境変数を除去
インストールの失敗	インストーラーのエラー透明性 — IDE 間のエラー分類 + 12×4 テストマトリックス

アーキテクチャ上のスコープを 1 行で書けない場合、そのクラスターのまとめ方は適切ではありません。

標準の誘導コメント

すべての子イシューをクローズする際に、次の文言をそのまま使用します。一貫性があれば、コントリビューターがパターンをすぐに把握でき、監査記録も検索しやすくなります。

Consolidating into #<MASTER> (plan-XX). The root cause and fix sequencing are tracked there alongside the rest of the cluster — please follow that issue for progress.

completed ではなく not planned としてクローズします。子イシューは作業単位ではなく、症状だったためです。

GitHub CLI の基本操作

リポジトリを特定します。

repo_json=$(gh repo view --json owner,name)
owner=$(jq -r '.owner.login // .owner.name' <<<"$repo_json")
repo=$(jq -r '.name' <<<"$repo_json")

オープン中のすべてのイシューを一覧表示します（すべてを読む作業）。注意点が 2 つあります。

• gh issue list --json comments が返すのはコメント本文ではなく、件数のプレースホルダーのみです。各イシューのコメントは gh issue view <N> --json comments で取得する必要があります。
• --limit を明示すると、バックログがそれより大きい場合に通知なく結果が切り詰められます。必ず最初にオープン中の総数を確認してください。

# 1. Confirm total — never trust an arbitrary --limit.
# Note: GitHub's REST API treats PRs as issues, so .open_issues_count
# from /repos/{owner}/{repo} is actually issues + PRs. Use the search
# API to get the issue-only count.
total=$(gh api "search/issues?q=repo:$owner/$repo+is:issue+is:open" --jq '.total_count')
echo "Open issues: $total"

# 2. List bodies (set --limit at or above the true total)
gh issue list --state open --limit "$total" \
  --json number,title,body,labels,author,createdAt

# 3. For each issue, fetch its full comment thread
for n in $(gh issue list --state open --limit "$total" --json number --jq '.[].number'); do
  echo "=== Issue #$n ==="
  gh issue view "$n" --json comments \
    --jq '.comments[] | "\(.author.login) (\(.createdAt)): \(.body)"'
done

total > 1000 の場合は、REST API を使用してページネーションします。結果の配列が空になるまで gh api "repos/$owner/$repo/issues?state=open&per_page=100&page=N" をループします（PR も含まれるため、select(.pull_request|not) でフィルターすることに注意してください）。

計画マスターを作成します。

gh issue create \
  --title "[plan-02] Spawn-Contract Templating — canonical \${CLAUDE_PLUGIN_ROOT} resolution across all hosts" \
  --body-file plans/02-spawn-contract-templating.md \
  --label plan,plan-02

統合コメントを投稿して子イシューをクローズします。

gh issue comment <CHILD> --body "Consolidating into #<MASTER> (plan-XX). The root cause and fix sequencing are tracked there alongside the rest of the cluster — please follow that issue for progress."
gh issue close <CHILD> --reason "not planned"

マスターに「Round N」トリアージコメントを追記します。

gh issue comment <MASTER> --body "$(cat <<'EOF'
**Round N consolidation**

- #<CHILD> (<one-line symptom>) folded into this plan as <classification>.

Proposed fix: <1–3 line sketch>.

Adds matrix cell: <host/IDE/shell combination>.
EOF
)"

最終状態を確認します。

gh issue list --state open --json number,title \
  | jq -r '.[] | "\(.number)\t\(.title)"'

出力には計画マスターのみを含めてください。

計画マスター本文のテンプレート

plans/0X-<slug>.md として保存し、マスターイシューの --body-file に指定します。

# [plan-XX] <Architectural Defect> — <one-line scope>

## Defect

<One paragraph: what is structurally broken, why it produces the observed family of symptoms.>

## Children

- #N — <symptom one-liner>
- #N — <symptom one-liner>
- ...

## Fix sequence

1. <First architectural change — bounded, reviewable>
2. <Second>
3. ...

## Test matrix

| Axis A | Axis B | Required behavior |
|---|---|---|
| ... | ... | ... |

The matrix lives in CI. A future regression must fail CI before a user can file.

## Out of scope

<What this plan deliberately does not cover, with pointers to other plan masters.>

ヘルスチェック

失敗パターンを検出するため、計画のマスターに対して定期的に実行します。

• 墓場化したマスター： マスターの Issue に、出荷 PR がないまま「Round N」コメントが5件以上追加されています。計画には強制力のある PR が必要です。そうでなければ分割します。
• 範囲が広すぎるマスター： 子 Issue の修正を1つの PR にまとめられません。範囲を絞った2つの計画に分割します。
• サーフェスでクラスタリングされたマスター： 子 Issue はトピックを共有していますが、修正内容は共有していません。根本原因ごとに再クラスタリングし、一部の子 Issue は別の計画に振り分けます。
• Issue とドキュメントの不整合： 計画マスターの本文と plans/0X-*.md の内容が一致していません。どちらかを正本（ドキュメント）として選び、それを基に Issue の本文を再生成します。

停止条件

クラスターパスの場合：gh issue list --state open がマスターのみを返したら停止します。

トリアージの場合：新しい子 Issue がクローズされ、マスターに Round-N の記録が追加されたら停止します。

バンドルの場合：PR がマージされ、一覧にあるすべての子 Issue が Closes #N によって自動クローズされたら停止します。

拒否すべき失敗パターン

• すべての Issue の本文を全文読む前にクラスタリングすること。 しないでください。
• マスターをオープンする前に子 Issue をクローズすること。 子 Issue には必ずリダイレクト先が必要です。
• 症状ではない Issue にリダイレクトコメントを使うこと（例：共通の根本原因がない正当な機能リクエスト）。そのような Issue はオープンのままにするか、独自のトラックに割り当てます。
• 一覧にあるすべての子 Issue が出荷される前にマスターをクローズすること。 マスターは契約です。早期にクローズすると監査証跡が損なわれます。