gh-notifications

GitHub 通知のトリアージ

概要

gh api を使って未読の GitHub 通知を取得し、ノイズを除外して重要度順に並べ、上位 N 件（デフォルトは 5 件）をクリック可能なリンク付きで表示します。gh CLI で認証済みである必要があります。

ワークフロー

1. 未読通知をすべて取得する

gh api notifications --paginate --jq '.[] | {
  id: .id,
  type: .subject.type,
  title: .subject.title,
  repo: .repository.full_name,
  updated: .updated_at,
  reason: .reason,
  url: .subject.url,
  latest_comment_url: .subject.latest_comment_url
}'

2. ノイズを除外する

順位付けの前に、重要度の低い通知タイプを削除します。

• 常に除外： CheckSuite（CI の成功／失敗）。通知自体から対応が必要になることはほとんどありません。
• 優先度を下げる： ユーザーが積極的に使用しているライブラリでない限り、サードパーティーのリポジトリからの Release 通知

3. 残りの通知を順位付けする

次の優先順位を適用します。

優先度	条件
P0 — 直接の対応が必要	reason が review_requested、assign、または mention
P1 — バグ修正とセキュリティ	タイトルに fix:、security、vulnerability、[BUG]、または breaking を含む
P2 — 活発に作業しているリポジトリ	ユーザーが所有する、または積極的に貢献しているリポジトリの PR と Issue
P3 — 機能開発	ユーザーが貢献しているリポジトリで、feat: を含む PR
P4 — その他すべて	ディスカッション、外部リポジトリの Issue、chore／refactor の PR、team_mention

各優先度内では、最終更新日時の新しい順に並べます。

重要：reason は 購読理由 であり、通知のきっかけ ではありません。 GitHub の reason フィールドは、ユーザーがそのスレッドを購読している理由を示します。これは固定されており、元の原因を反映します。今回の未読通知を発生させたものを示すわけではありません。スレッド内でユーザーが一度 @メンションされると、後から無関係なコメントが追加された場合や、ラベルが変更された場合、またはボットが Issue をクローズした場合でも、reason はずっと mention のままです。そのため、未読になったスレッドには引き続き reason: mention が付与されます。つまり、reason: mention は「たった今メンションされた」ではなく、「3 年前にメンションされ、誰かがたった今コメントした」という意味の場合があります。

その結果、スレッドの最新のアクティビティがユーザーと無関係なのに mention／review_requested が固定されている場合、それは新たな依頼ではなく、古いノイズであることがよくあります。P0 に順位付けする前に、最新のイベントが実際にユーザーに関係するものか（手順 4 を参照）を必ず確認してください。

reason フィールドの意味（GitHub REST API ドキュメントより）。 これらは異なる値です。混同しないでください。

• mention — スレッド内のどこかで（本文だけでなくコメントも含めて）、ユーザーが個人宛てに @メンションされたことがあります。固定されます。上記の警告を参照してください。
• team_mention — ユーザー本人ではなく、ユーザーが所属するチームが @メンションされました。通知のシグナルが弱いため、デフォルトでは P4 です。
• review_requested — ユーザーまたはその所属チームのいずれかがレビューを依頼されました。P0 ですが、これも固定されます。まだオープンで、ユーザーに割り当てられていることを確認してください。
• assign — Issue／PR に割り当てられました。author — ユーザーがスレッドを開始しました。comment — ユーザーがコメントしたスレッドでアクティビティがありました。subscribed — リポジトリをウォッチしています。manual — 明示的に購読しました。state_change — ユーザーがクローズ／マージしました。ci_activity — ユーザーが実行したワークフローが完了しました。

4. サブスクリプションの理由だけでなく、トリガーを特定する（P0 候補）

reason は固定されたままです（ステップ 3 の警告を参照）。そのため、P0 に見える mention／review_requested が古い情報の場合があります。P0 に分類する前に、直近のイベントが実際には何だったのか、それがユーザーに関係するものかを確認してください。ユーザーが関与した日付と、通知の updated_at を比較します。このステップはP0 候補のみ（少数）を対象に実行してください。すべての通知を確認する必要はありません。候補ごとに API 呼び出しが 1～2 回余分に必要になります。

一覧のレスポンスには、すでに最新のコメントを指す subject.latest_comment_url が含まれています。コメントをすべて再取得するのではなく、この URL を直接取得してください。ただし、これはコメントのみを指します。トリガーがコメント以外のイベント（Issue のクローズ、ラベル付け、再オープン）の場合、latest_comment_url は古い情報か null です。その場合は、Issue の状態または Timeline API を確認してください。

ME=$(gh api user --jq '.login')

# Cheapest: fetch the exact comment that bumped the thread (from subject.latest_comment_url)
gh api {latest_comment_url} --jq '{user: .user.login, created: .created_at, url: .html_url, body: .body}'

# Catch non-comment triggers (close/reopen/label) that latest_comment_url misses
gh api repos/{owner}/{repo}/issues/{n} --jq '{state, closed_at, updated_at}'

# Where/when was the user actually @mentioned? (may be old). NOTE: pipe to standalone jq — gh api has no --arg
gh api repos/{owner}/{repo}/issues/{n}/comments \
  | jq --arg me "$ME" '.[] | select(.body | test("@" + $me + "(?![A-Za-z0-9-])"; "i")) | {user: .user.login, created: .created_at, url: .html_url, body: .body}'

# Full event fidelity (who did what, when) — every close/label/mention/review as discrete events
gh api repos/{owner}/{repo}/issues/{n}/timeline --jq '.[] | {event: .event, actor: .actor.login, created: .created_at}'

判断基準：

• 最新のイベントがユーザーに関係する（新しい @メンション、レビューのリクエスト、ユーザーのコメントへの返信）→ P0 のままにし、そのイベントへのディープリンク（.html_url）を付けて引用します。
• 最新のイベントが無関係（他のユーザーのコメント、ボットによる Issue のクローズ／ラベル付け、別のユーザーによる state_change）→ 優先度を下げます。たとえば、「2023 年にメンション；@other による新しいコメントで再浮上」や「Issue はボットがクローズ — おそらくアーカイブのみ」と正確に記載します。新たな依頼のように提示しないでください。

5. クリック可能なリンクを作成する

API URL をブラウザー用 URL に変換します：

• https://api.github.com/repos/{owner}/{repo}/pulls/{n} → https://github.com/{owner}/{repo}/pull/{n}
• https://api.github.com/repos/{owner}/{repo}/issues/{n} → https://github.com/{owner}/{repo}/issues/{n}
• Discussion タイプの場合は、次の URL を組み立てます：https://github.com/{owner}/{repo}/discussions

6. 結果を提示する

次の項目を含む番号付きリストを出力します：

• 優先度タグ（P0～P4）
• 通知タイプ（Issue、PR、Discussion）
• タイトル
• クリック可能な GitHub リンク（mention 項目はメンションされたコメントへのディープリンク）
• 優先度が高い理由の簡潔な説明（短いフレーズ 1 つ）。メンションの場合は、誰が書いたかを示し、@メンションを引用します。「あなたがメンションされました」だけでは不十分です。

出力例：

1. [P0] PR: feat: Add stress testing helper endpoints
   https://github.com/protokol/dpp-api/pull/343
   Review requested from you

2. [P1] Issue: [BUG] Statusline context_window JSON...
   https://github.com/anthropics/claude-code/issues/13783
   Bug report, updated today

3. [P4] Issue: AWS::CertificateManager::Certificate deletion fails...
   https://github.com/aws-cloudformation/cloudformation-coverage-roadmap/issues/837
   reason=mention but stale: you were @mentioned in 2023; resurfaced by @marat-affinidi's new comment — not a fresh ask

7. 後続の操作を提案する

上位 N 件を提示した後、次のように尋ねます：

• 「残りを既読にしますか？」
• 「この中から開きたいものはありますか？」

カスタマイズ

ユーザーは引数を指定してこのスキルを実行できます：

• /gh-notifications — 既定では上位 5 件
• /gh-notifications 10 — 上位 10 件
• /gh-notifications --mark-read — 提示後、上位以外の通知も既読にする

よくある間違い

• 通知の詳細を 1 件ずつ取得しないでください（N+1 API 呼び出し）。必要な情報は --jq を使用して、1 回のページネーション付き呼び出しで抽出します
• 生の API URL を表示しないでください。必ずクリック可能な github.com リンクに変換します
• ランク付けした結果に CheckSuite 通知を含めないでください。ノイズにしかなりません
• reason をトリガーとして扱わないでください。固定されたサブスクリプションの理由です。reason: mention は「何年も前にメンションされ、たった今誰かがコメントした」という意味の場合があります。P0 に分類する前に、必ず最新のイベント（ステップ 4）を確認してください
• reason フィールドを根拠に、現在形で「あなたがメンションされています」と断定しないでください。メンションはたいてい古く、コメントに埋もれています。いつ、どこで発生したのか、現在の通知を誰が発生させたのかを確認してください
• team_mention を個人への mention として扱わないでください。これはあなたではなく、所属チームがタグ付けされたことを意味します。これらは別々の reason 値です