tag-duplicate-prs-issues

重複する PR と Issue にタグを付ける

メンテナーが、プルリクエストまたは Issue が既存の作業と重複しているか判断する必要がある場合に、このスキルを使用します。

このスキルは、メンテナーによるトリアージとグループ化のためのものです。 PR の実装品質をレビューするためのものではありません。

必要なセットアップ

このセットアップが完了するまで、重複グループや注釈を書き込まないでください。 読み取り専用の調査は、引き続き gitcrawl とライブの gh で進められます。

関連スキル

ローカルでの候補の検出には、まず $gitcrawl を使用してください。 利用可能な場合は、prtags リポジトリの skills/prtags/SKILL.md にある prtags スキルを使用してください。

CLI のインストール

以下で指定された固定リリースから prtags をインストールしてください。 メンテナーが未リリースの動作をテストすることを明示的に希望していない限り、古いローカルビルドに依存しないでください。

prtags CLI のインストールコマンド：

GOBIN="$HOME/.local/bin" go install github.com/dutifuldev/prtags/cmd/[email protected]

prtags は OpenClaw 組織の外部にあるため、このインストールでは、Go モジュールプロキシが解決し、公開チェックサムデータベースが検証するレビュー済みバージョンに固定しています。GOBIN によって、インストールされた実行ファイルは以前のインストーラーと同じユーザーローカルディレクトリに配置されるため、既存の $HOME/.local/bin の PATH で新たにインストールしたバージョンを引き続き実行できます。 リモートスクリプトをシェルにパイプしてインストールしたり、ブランチを指定してインストールしたりしないでください。どちらの方法も、実行時にそのサードパーティが提供するものを、メンテナー自身の権限で実行することになります。新しい prtags リリースへの更新は、このファイルへのレビュー済みの変更として行い、作業中には行わないでください。

prtags の認証

prtags は、メンテナー自身の GitHub アカウントで OAuth デバイスフローを使ってログインしてください。対話形式でのトリアージに、共有メンテナートークンを使用しないでください。

prtags auth login
prtags auth status

想定される結果は、prtags がログインしたメンテナーの ID をローカルに保存し、認証が必要な書き込みにそのアカウントを使用することです。

セットアップ不足時のルール

ワークフローを開始する前に、事前確認を済ませる必要はありません。 ツールやアカウントの状態が実際に必要になるまでは、通常の手順を進めてください。

書き込みの段階で prtags が見つからない、またはログインしていないと判明した時点で、直ちに停止してください。 その後、部分的な書き込みモードで処理を続けないでください。

prtags が見つからない場合は、CLI のインストール にある固定インストールコマンドを実行するようユーザーに依頼してください。 インストールするバージョンの唯一の情報源としてそのセクションを維持し、別のインストール方法を独自に考案しないでください。

prtags auth status でユーザーがログインしていないと表示された場合は、次のコマンドを実行するようユーザーに依頼してください。

prtags auth login

不足していたツールまたはログイン状態が解決された後にのみ、作業を再開してください。

読み取り経路の既定

このワークフローで候補を見つける際は、まず gitcrawl を使用してください。 関連する Issue、重複としての試み、クローズ済みのスレッドについて、ローカルの履歴とクラスタリングを行うレイヤーとして扱ってください。

実行可能な判断を下す前に、対象スレッドと各候補について、ライブの gh または gh api を使用してください。 次のような具体的な理由で gitcrawl がない、または古い場合は、ライブの GitHub を使用してください。

• 対象または候補がまだ存在しない
• 判断に必要なローカルデータが明らかに古い、または不完全である
• gitcrawl がエラーになる、タイムアウトする、または必要な近傍データや検索データがない

ライブの GitHub 検索に切り替えた場合は、その旨と理由を記録してください。

後の段階で、prtags 自身のミラーが追いついていないために対象レベルの書き込みが失敗した場合は、強制的に代替手段で書き込まず、キュレーションバックエンドに対象オブジェクトがないことを報告して停止してください。

目標

各対象 PR または Issue について：

1. 重複を示す証拠を集める
2. 実際に重複しているか判断する
3. その重複クラスター用の prtags グループを新規作成するか、既存のものを再利用する
4. メンテナーの判断を prtags に保存する
5. その連携が設定されている場合は、通常の prtags グループ書き込みによって GitHub コメントの同期が行われるようにする

ツールの役割

以下の役割分担に従ってツールを使用してください。

• gitcrawl は候補の生成と過去の情報の確認に使用します
  • まずローカルでタイトルや本文を検索し、近隣項目、クラスター、クローズ済みスレッドを確認します
  • ライブの GitHub で確認するまでは、候補はすべて手がかりとして扱ってください
• gh はライブの GitHub の正として使用します
  • 対象の状態、本文、コメント、レビュー、ファイル、関連する issue、現在の open／closed／merged 状態の確認に使用します
  • gitcrawl の情報が古い、不足している、または必要なクエリを表現できない場合にのみ、gh search を使用します
• prtags はメンテナーによるキュレーション層です
  • 重複グループを1つ作成するか、既存のものを再利用するために使用します
  • 重複ステータス、確度、根拠、グループの概要を保存するために使用します
  • GitHub に表示するグループコメントの正として使用します

作業ルール

• タイトルが似ているという理由だけで、重複と判断しないでください。
• 同じファイルが変更されているという理由だけで、重複と判断しないでください。
• 重複クラスターは、ユーザー向けの問題、意図、実装または調査の文脈が実質的に重なっていることに基づいて作成してください。

1グループのルール

重複グループは排他的なものとして扱ってください。 PR または issue が同時に所属できる重複グループは、最大1つです。

つまり、次のとおりです。

• 新しいグループを作成する前に、同じ重複の経緯をすでに表している既存のグループを検索します
• 対象が別の重複グループにすでに属しているように見える場合は、まずその競合を解決してください
• 表現が少し異なるという理由だけで、同じ対象について2つ目のグループを作成しないでください
• 既存のグループが2つ重複している可能性があり、安全に統合できるか判断できない場合は、作業を止めてメンテナーに確認してください

このルールは速度よりも重要です。 このスキルでは、同じ問題について一貫した重複クラスターを1つ維持し、類似したクラスターを多数作らないようにします。

適切な重複グループが表すもの

重複グループでは、根本的な問題と意図される修正方針を説明してください。 キーワードが共通しているという理由だけで項目をグループ化しないでください。

適切なグループの例：

• ユーザー向けの同じバグ、またはメンテナー向けの同じタスク
• 同じサブシステムまたはコード領域
• 同じ意図された変更方針
• 同じ可能性の高い重複解決方法

不適切なグループの例：

• 「Slack に関係するすべての PR」
• 「retry に言及しているすべての issue」
• 「認証関連のすべての項目」

グループのタイトルには実際の問題を記載してください。 グループの説明では、意図とコード領域を要約してください。

例：

• gateway: startup regression from channel status bootstrap
• whatsapp: QR preflight timeout handling
• release: cross-OS validation handoff gaps

根拠のチェックリスト

重複と判断する前に、少なくとも2つのカテゴリから根拠を集めてください。 gitcrawl の近隣項目、検索結果、クラスターへの所属は候補の生成にあたり、それだけでは十分な証拠になりません。

PR の場合：

• 同一またはほぼ同じ問題の説明
• 同じ変更ファイル、または重複するファイル範囲
• 同じ修正方針
• 同じサブシステムと障害モード
• 同じ関連 issue、または同じユーザーに見える症状

issue の場合：

• 同じユーザーに見える問題
• 同じ再現手順、または同じ障害モード
• 同じ可能性の高い修正領域
• すでに関連付けられている、または議論されている同じ PR
• メンテナーがすでに同じ重複グループへの分類を促している

表現の類似性しかない場合、それだけでは不十分です。

ステップ1：対象を読む

まず対象そのものを読みます。 対象の現在の状態は、ライブの GitHub で確認してください。

PR の場合：

gh pr view <number> --json number,title,state,mergedAt,body,closingIssuesReferences,files,comments,reviews,statusCheckRollup

issue の場合：

gh issue view <number> --json number,title,state,body,comments,closedAt

以下を記録します。

• 対象の種類と番号
• タイトル
• 問題の説明
• 提案されている意図
• サブシステム
• open、closed、merged のいずれであるか
• 人間によって言及された、重複候補となるスレッドがすでにあるかどうか

ステップ 2：Gitcrawl で幅広く検索する

ローカルの OpenClaw 履歴とクラスタリングのソースである gitcrawl を最初に使います。 gitcrawl にデータがない、古い、または動作していない場合を除き、幅広い GitHub のライブ検索に切り替えないでください。

対象と関連するスレッドから始めます：

gitcrawl threads openclaw/openclaw --numbers <issue-or-pr-number> --include-closed --json
gitcrawl neighbors openclaw/openclaw --number <issue-or-pr-number> --limit 20 --json

次に、キーフレーズとサブシステムの用語を検索します：

gitcrawl search openclaw/openclaw --query "<key phrase from title or body>" --mode hybrid --limit 20 --json
gitcrawl search openclaw/openclaw --query "<subsystem or error phrase>" --mode hybrid --limit 20 --json

関連性の高そうなクラスターを調べます：

gitcrawl cluster-detail openclaw/openclaw --id <cluster-id> --member-limit 20 --body-chars 280 --json

PR については、ライブのファイルデータを使ってコードの重複がありそうか確認します：

gh pr view <candidate-pr> --json number,title,state,mergedAt,files,body,comments,reviews

Issue については、重複の可能性がある Issue の状態とコメントをライブで確認します：

gh issue view <candidate-issue> --json number,title,state,body,comments,closedAt

ステップ 3：情報の不足をライブの GitHub 検索で補う

次の場合は、gitcrawl の使用後に対象を絞ったライブの GitHub 検索を行います：

• 対象が新しすぎてローカルストアにない
• コメントやレビューが重要だが、ローカルストアにない
• 正確なフレーズがローカルの検索結果に現れなかったものの、対象の Issue／PR が十分に新しく、GitHub なら把握しているはずである

gh search prs --repo openclaw/openclaw --match title,body --limit 50 -- "<key phrase>"
gh search issues --repo openclaw/openclaw --match title,body --limit 50 -- "<key phrase>"
gh search issues --repo openclaw/openclaw --match comments --limit 50 -- "<error or maintainer phrase>"

ステップ 4：結果を決定する

次のいずれかを選択します：

• not_duplicate
• duplicate_needs_judgment
• duplicate_confirmed

重複項目を安全にクローズまたは再タグ付けできるだけの強い根拠がある場合に限り、duplicate_confirmed を使用します。

次の場合は duplicate_needs_judgment を使用します：

• 問題は同じように見えるものの、実装の目的が異なる
• コードの重複が弱い
• Issue の記述が曖昧である
• 重複グループの解釈が二通りあり、どちらも妥当である可能性がある
• 対象が既存の二つの重複グループにまたがっているように見える

ステップ 5：prtags グループを再利用するか、一つ作成する

グループを作成する前に、既存のグループがないか prtags で検索します。

まずグループをテキスト検索します：

prtags search text -R openclaw/openclaw "<problem phrase>" --types group --limit 10
prtags search similar -R openclaw/openclaw "<problem summary>" --types group --limit 10
prtags group list -R openclaw/openclaw

関連性の高そうなグループを調べます：

prtags group get <group-id>
prtags group get <group-id> --include-metadata

次の場合は既存のグループを再利用します：

• 同じ問題を表している
• 明らかに関連するメンバーがすでに含まれている
• 対象を追加してもグループの一貫性が保たれる

gitcrawl が複数の PR や Issue を近くに分類したという理由だけで、既存のグループの範囲を広げないでください。 新しいメンバーを追加する前に、実際の実装経路とメンテナーの意図が引き続き一致することを確認します。

既存のグループが明らかに適合しない場合に限り、新しいグループを作成します。

問題を基にしたタイトルと意図を基にした説明でグループを作成します：

prtags group create -R openclaw/openclaw \
  --kind mixed \
  --title "<problem-centered title>" \
  --description "<same intent, subsystem, and duplicate-resolution path>" \
  --status open

次に、対象と判明している重複メンバーを関連付けます：

prtags group add-pr <group-id> <pr-number>
prtags group add-issue <group-id> <issue-number>

対象がすでに別の重複グループに属しているように見え、そのグループを安全に再利用できない場合は、そこで止めます。 二つ目のグループを作成しないでください。

ステップ 6：アノテーションフィールドが存在することを確認する

スキルを冪等にするため、field ensure を使用します。

推奨する対象レベルのフィールド：

prtags field ensure -R openclaw/openclaw --name duplicate_status --scope pull_request --type enum --enum-values not_duplicate,candidate,confirmed --filterable
prtags field ensure -R openclaw/openclaw --name duplicate_status --scope issue --type enum --enum-values not_duplicate,candidate,confirmed --filterable
prtags field ensure -R openclaw/openclaw --name duplicate_confidence --scope pull_request --type enum --enum-values low,medium,high --filterable
prtags field ensure -R openclaw/openclaw --name duplicate_confidence --scope issue --type enum --enum-values low,medium,high --filterable
prtags field ensure -R openclaw/openclaw --name duplicate_rationale --scope pull_request --type text --searchable
prtags field ensure -R openclaw/openclaw --name duplicate_rationale --scope issue --type text --searchable

推奨するグループレベルのフィールド：

prtags field ensure -R openclaw/openclaw --name duplicate_confidence --scope group --type enum --enum-values low,medium,high --filterable
prtags field ensure -R openclaw/openclaw --name duplicate_rationale --scope group --type text --searchable
prtags field ensure -R openclaw/openclaw --name cluster_summary --scope group --type text --searchable

ステップ 7：メンテナーの判断を prtags に保存する

PR の場合：

prtags annotation pr set -R openclaw/openclaw <pr-number> \
  duplicate_status=confirmed \
  duplicate_confidence=high \
  duplicate_rationale="<same problem, same fix direction, overlapping files and comments>"

Issue の場合：

prtags annotation issue set -R openclaw/openclaw <issue-number> \
  duplicate_status=confirmed \
  duplicate_confidence=high \
  duplicate_rationale="<same user-visible problem and same intended fix path>"

グループの場合：

prtags annotation group set <group-id> \
  duplicate_confidence=high \
  cluster_summary="<one-sentence problem summary>" \
  duplicate_rationale="<why these items belong in one duplicate cluster>"

根拠が不十分な場合は、duplicate_status=candidate に設定し、信頼度を下げます。

prtags が対象を解決できず、PR または Issue ごとのアノテーションの書き込みに失敗した場合は、代替の書き込み経路を無理に使わないでください。 書き込み可能なグループの状態は保持し、キュレーションバックエンドで対象オブジェクトがまだ見つからないことを報告して、prtags が追いつくまで対象レベルのアノテーションを保留します。

ステップ 8：prtags にグループコメントを同期させる

エージェントに GitHub のコメントを直接作成するよう指示しないでください。 prtags は、グループの状態から派生する GitHub へのコメントを管理します。

通常は、コメントの同期を手動で開始しないでください。 コメントの同期が設定されている場合、グループへの書き込みによって派生コメントの同期が自動的にキューに追加されます。

手動同期は、修復または再試行のためにのみ使用します：

prtags group sync-comments <group-id>

メンテナーが対応の必要なグループを確認する必要がある場合は、次を使用します：

prtags group list-comment-sync-targets -R openclaw/openclaw

スキルでは、GitHub コメントを、適切な prtags グループ状態の結果として扱います。 手動でのコメント作成を、通常の重複対応ワークフローの一部として扱わないでください。 また、重複に関する判断のたびに sync-comments が必須の手順であるとも扱わないでください。

出力形式

次のセクションで、メンテナー向けの短いレポートを返します：

Decision: duplicate_confirmed | duplicate_needs_judgment | not_duplicate
Target: PR #<n> | Issue #<n>
Confidence: high | medium | low

Evidence:
- ...
- ...
- ...

prtags actions:
- reused group <group-id> | created group <group-id>
- added members: ...
- annotations written: ...
- comment sync: automatic if configured | manual repair triggered for <group-id>

停止条件

次の場合は、重複と無理に判断せず、作業を停止してエスカレーションしてください。

• 対象が異なる 2 つの重複グループに属するように見える場合
• 重複グループの分類が不明確な場合
• 文言は一致していても、実装の目的が異なる場合
• 2 つの PR が異なる理由で同じファイルを変更している場合
• 2 つの Issue が似た症状を説明していても、根本原因は異なる可能性が高い場合

メンテナーには、明確な重複判定か、明示的な「要判断」という結果のどちらかを提示してください。 曖昧にしてはいけません。