update-issue-index

Update Issues INDEX.md

docs/issues/INDEX.md の「一覧」テーブルを、gh / git の現在状態から再生成する手動発火スキル。

SDD 運用で issue / PR が増えるほど INDEX.md は実態と乖離しがちなので、任意のタイミングで一発更新できるようにしたもの。発火は手動のみで、hook 登録は行わない。

---

付属スクリプト

プラグインとしてインストールされると、スクリプトは ${CLAUDE_PLUGIN_ROOT%/}/skills/update-issue-index/scripts/ 配下に展開される。呼び出し時は bash の parameter expansion ${VAR%/} で末尾スラッシュを剥がす形で統一する(CLAUDE_PLUGIN_ROOT は末尾スラッシュ付きで展開されるため、そのまま連結すると // が混入する)。作業ディレクトリ(cwd)はユーザーのプロジェクトのままで OK。

スクリプト	役割	使い方
generate-index.sh	INDEX.md のテーブルをマーカー間で再生成	bash "${CLAUDE_PLUGIN_ROOT%/}/skills/update-issue-index/scripts/generate-index.sh" [INDEX_FILE]

INDEX_FILE 省略時は docs/issues/INDEX.md を対象にする。スクリプトは INDEX.md を in-place で書き換える。差分の提示とコミット判断は Claude(このスキル)側の責務。

---

マーカーの前提

docs/issues/INDEX.md には以下のマーカーが必要。スクリプトはこの 2 行の間をテーブルで置き換える。

<!-- BEGIN_ISSUE_TABLE -->
| # | タイトル | status | ブランチ | PR |
| --- | --- | --- | --- | --- |
| ... |
<!-- END_ISSUE_TABLE -->

マーカーが無い INDEX.md に対してはスクリプトがエラーで終了する。初回導入時はマーカーを手動で追加する。

---

ワークフロー

ステップ 1: スクリプトを実行

bash "${CLAUDE_PLUGIN_ROOT%/}/skills/update-issue-index/scripts/generate-index.sh"

エラー終了したら内容をユーザーに報告して中断する。よくある原因:

• gh auth login されていない
• 現在地が git リポジトリの外
• INDEX.md にマーカーが無い

ステップ 2: 差分を確認

git diff -- docs/issues/INDEX.md

差分の有無で分岐する。

• 差分なし: 「INDEX.md は既に最新です」とユーザーに報告して終了する。コミットしない。
• 差分あり: diff の内容(追加/変更/削除された行)をユーザーに提示する。長い場合は「追加 N 行 / 変更 N 行 / 削除 N 行」のサマリと、特徴的な変化(新規 issue が追加された、status が open → pr-open に変わった 等)を抜粋する。

ステップ 3: コミット判断【チェックポイント】

ユーザーに「コミットしますか?」と明示的に確認する。自動でコミットしない。

ユーザーが「コミットして」等の明示指示をしたら、次のコマンドでコミットする:

git add docs/issues/INDEX.md
git commit -m "docs: refresh issues INDEX.md"

コミットメッセージの書式はこの形式で固定(SDD 運用上、INDEX.md の更新はメタ作業なので Conventional Commits の docs: 固定でよい)。

ユーザーが「コミットしない」「確認だけ」等と言った場合は、書き換え済みの INDEX.md をワーキングツリーに残したまま終了する(ユーザーが手動で編集・コミット・捨てられる)。

ステップ 4: 結果を報告

• 差分の有無
• コミットしたならコミットハッシュ、していないなら「ワーキングツリーに変更を残しています」
• 次にユーザーがやるべきこと(push、別ブランチへの持ち込み等、該当すれば)

---

status 判定ロジック

スクリプトは各 issue に対して以下の順で status を判定する:

1. マージ済 PR が紐付いている → merged
2. OPEN な PR が紐付いている → pr-open
3. 実装ブランチ(issue-<N> をパス要素として含む)が存在 & PR 無し → in-progress
4. Issue が OPEN & 上記いずれも該当せず → open
5. Issue が CLOSED & マージ済 PR も無し → closed

PR と issue の紐付けは以下のどちらかで判定する:

• PR のブランチ名に issue-<N> をトークンとして含む(例: feature/issue-7-foo, fix/issue-2)
• PR 本文に Closes #<N> / Fixes #<N> / Resolves #<N> を含む(大文字小文字問わず)

複数候補がある場合: PR は OPEN > MERGED > CLOSED、ブランチはローカル優先(アルファベット順先頭)。

---

例

例 1: 更新不要のケース

ユーザー: 「INDEX を更新して」

動き:

1. generate-index.sh を実行
2. git diff → 差分なし
3. 「INDEX.md は既に最新です」と報告して終了

例 2: 新規 issue と PR 状態変化が反映されるケース

ユーザー: 「INDEX 最新にして」

動き:

1. generate-index.sh を実行
2. git diff → issue #8 の行が追加、issue #2 が open → pr-open に変化
3. 差分要約をユーザーに提示:
   • + | 8 | ... | open | - | - |
   • - | 2 | ... | open | - | - | → + | 2 | ... | pr-open | fix/issue-2-... | #6 |
4. ユーザー: 「コミットして」
5. git add + git commit -m "docs: refresh issues INDEX.md"
6. コミットハッシュを報告

---

注意点

• 手動発火のみ: このスキルは hook に登録しない設計。PR / issue の自動操作フックで動かすと、想定外のタイミングで差分が発生し rebase や CI を混乱させる可能性がある。
• マーカー必須: INDEX.md に <!-- BEGIN_ISSUE_TABLE --> / <!-- END_ISSUE_TABLE --> が無いとスクリプトはエラー終了する。初回導入時はユーザーに相談の上、マーカーを追加する(冒頭説明と「status の語彙」セクションはマーカー外なので保持される)。
• 自動 commit しない: 差分が出ても、ユーザーの明示指示があるまで絶対にコミットしない。INDEX.md が意図しないコミットに混入すると厄介なので、ここは守る。
• push はしない: コミットしても push は別行動。ユーザーの指示時のみ git push する。
• ブランチ: このスキルは現在のブランチに対して INDEX.md をコミットする。通常はデフォルトブランチでの運用を想定するが、他ブランチで作業中に更新したい場合もあるので、ブランチチェックは強制しない(必要ならユーザーに一言確認する程度)。
• 大量 issue のリポでの性能: gh issue list --limit 1000 と gh pr list --limit 1000 を呼ぶ。1000 を超えるリポでは取りこぼしが起きる可能性あり(その時は --limit の調整が必要)。
• タイトルのエスケープ: タイトルに | が含まれるとテーブルが崩れるので、スクリプト側で \| にエスケープする。改行もスペースに変換する。
• status 判定の限界: 「ブランチ有り & PR 無し」を in-progress と判定するが、実装を放棄したまま残っているブランチも in-progress になる。気になるときはユーザーが手動で該当ブランチを削除すれば次回の生成で正しい status に落ち着く。