重複PR/Issueのタグ付け

重複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. その重複クラスタに対して1つのprtagsグループを作成または再利用する
4. メンテナーの判断をprtagsに保存する
5. 通常のprtagsグループ書き込みに依存して、その統合が設定されている場合にGitHubコメント同期を駆動する

ツールの役割

以下の境界でツールを使用します:

• gitcrawlは候補生成と履歴コンテキスト
  • 最初にローカルタイトル/本文検索、近傍、クラスタ、クローズスレッドの発見に使用する
  • すべての候補を、稼働中のGitHubが確認するまでのリードとして扱う
• ghは稼働中のGitHubの真実
  • ターゲットの状態、本文、コメント、レビュー、ファイル、リンクされたIssue、現在のオープン/クローズ/マージ状態に使用する
  • gitcrawlが古い、データが欠落している、または必要なクエリを表現できない場合にのみgh searchを使用する
• prtagsはメンテナーキュレーションレイヤー
  • 1つの重複グループを作成または再利用するために使用する
  • 重複状態、信頼度、根拠、グループサマリーを保存するために使用する
  • GitHub向けグループコメントの真実の情報源として使用する

作業ルール

• タイトルが類似しているという理由だけで重複と呼んではいけません。
• 同じファイルが変更されたという理由だけで重複と呼んではいけません。
• 重複クラスタは、同じユーザー向け問題、同じ意図、および実質的に重複する実装または調査コンテキストに基づく必要があります。

1グループルール

重複グループを排他的として扱います。 PRまたはIssueは、一度に最大1つの重複グループに属する必要があります。

つまり:

• 新しいグループを作成する前に、同じ重複ストーリーを既に表している既存のグループを検索する
• ターゲットが既に別の重複グループに属しているように見える場合は、停止し、まずその競合を解決する
• 文言が少し異なるだけの理由で、同じターゲットに対して2つ目のグループを作成しない
• 2つの妥当な既存グループが重複しており、判断を安全にマージできない場合は、停止し、メンテナーに問い合わせる

このルールは速度よりも重要です。 このスキルは、問題ごとに1つの一貫した重複クラスタを維持し、多くの類似した重複クラスタを維持しないようにする必要があります。

良い重複グループが表すもの

重複グループは、根本的な問題と意図された修正の方向性を説明する必要があります。 キーワードを共有するという理由だけでアイテムをグループ化しないでください。

良いグループの形状:

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

悪いグループの形状:

• 「Slackに触れるすべてのPR」
• 「リトライに言及するすべてのIssue」
• 「認証関連のすべてのアイテム」

グループタイトルは実際の問題を命名する必要があります。 グループ説明は意図とコード面を要約する必要があります。

例:

• gateway: channel status bootstrapからの起動時回帰
• whatsapp: QRプリフライトタイムアウト処理
• release: クロスOS検証ハンドオフのギャップ

エビデンスチェックリスト

重複を宣言する前に、少なくとも2つのカテゴリからエビデンスを収集します。 gitcrawlの近傍、検索ヒット、クラスタメンバーシップは候補生成としてカウントされ、それだけでは十分な証拠とはなりません。

PRの場合:

• 同じまたはほぼ同じ問題ステートメント
• 同じ変更ファイルまたは重複するファイル範囲
• 同じ修正方向
• 同じサブシステムと障害モード
• 同じリンクされたIssueまたは同じユーザーから見える症状

Issueの場合:

• 同じユーザーから見える問題
• 同じ再現ストーリーまたは同じ障害モード
• 同じ可能性の高い修正領域
• 既にリンクまたは議論されている同じPR
• 同じ重複グループ化に向けて同じメンテナーが既に誘導している

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

ステップ 1: ターゲットを読む

まず、ターゲット自体を読みます。 現在のターゲット状態には稼働中のGitHubを使用します。

PRの場合:

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

Issueの場合:

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

記録:

• ターゲットタイプと番号
• タイトル
• 問題ステートメント
• 提案された意図
• サブシステム
• オープン、クローズ、マージ済みのいずれか
• 人間によって言及された可能性のある重複スレッドが既にあるかどうか

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

gitcrawlを最初に使用します。なぜなら、それがローカルのOpenClaw履歴とクラスタリングソースだからです。 gitcrawlがデータを欠落している、古い、または失敗している場合を除き、広範な稼働中のGitHub検索に切り替えないでください。

ターゲットとその近傍のスレッドから開始:

gitcrawl threads openclaw/openclaw --numbers <IssueまたはPR番号> --include-closed --json
gitcrawl neighbors openclaw/openclaw --number <IssueまたはPR番号> --limit 20 --json

次に、キーフレーズとサブシステム用語を検索:

gitcrawl search openclaw/openclaw --query "<タイトルまたは本文からのキーフレーズ>" --mode hybrid --limit 20 --json
gitcrawl search openclaw/openclaw --query "<サブシステムまたはエラーフレーズ>" --mode hybrid --limit 20 --json

可能性の高いクラスタを検査:

gitcrawl cluster-detail openclaw/openclaw --id <クラスタID> --member-limit 20 --body-chars 280 --json

PRの場合、ライブファイルデータで可能性の高いコード重複を確認:

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

Issueの場合、可能性の高い重複Issueの状態とコメントをライブで確認:

gh issue view <候補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 -- "<キーフレーズ>"
gh search issues --repo openclaw/openclaw --match title,body --limit 50 -- "<キーフレーズ>"
gh search issues --repo openclaw/openclaw --match comments --limit 50 -- "<エラーまたはメンテナーフレーズ>"

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

以下の結果のいずれかを選択します:

• not_duplicate（重複ではない）
• duplicate_needs_judgment（判断が必要な重複）
• duplicate_confirmed（重複確認済み）

duplicate_confirmedは、メンテナーが安全に重複アイテムをクローズまたは再タグ付けできるほどエビデンスが強い場合にのみ使用します。

duplicate_needs_judgmentは以下の場合に使用します:

• 問題は同じに見えるが、実装目標が異なる
• コードの重複が弱い
• Issueの文言があいまい
• 2つの有効な重複グループ解釈が存在する可能性がある
• ターゲットが2つの既存の重複グループと交差しているように見える

ステップ 5: 1つのprtagsグループを再利用または作成する

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

グループのテキスト検索から開始:

prtags search text -R openclaw/openclaw "<問題フレーズ>" --types group --limit 10
prtags search similar -R openclaw/openclaw "<問題サマリー>" --types group --limit 10
prtags group list -R openclaw/openclaw

可能性の高いグループを検査:

prtags group get <グループID>
prtags group get <グループID> --include-metadata

以下の場合に既存のグループを再利用します:

• 同じ問題を表している
• 明確に関連するメンバーを既に含んでいる
• ターゲットを追加してもグループの一貫性が保たれる

gitcrawlがいくつかのPRまたはIssueを互いに近くに配置したという理由だけで、既存のグループを拡大しないでください。 新しいメンバーを追加する前に、実際の実装パスとメンテナーの意図がまだ一致していることを確認します。

明確に適合する既存のグループがない場合にのみ、新しいグループを作成します。

問題ベースのタイトルと意図ベースの説明でグループを作成します:

prtags group create -R openclaw/openclaw \
  --kind mixed \
  --title "<問題中心のタイトル>" \
  --description "<同じ意図、サブシステム、重複解決パス>" \
  --status open

次に、ターゲットと既知の重複メンバーをアタッチします:

prtags group add-pr <グループID> <PR番号>
prtags group add-issue <グループID> <Issue番号>

ターゲットが既に別の重複グループに属しているように見え、そのグループを安全に再利用できない場合は、停止します。 2つ目のグループを作成しないでください。

ステップ 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番号> \
  duplicate_status=confirmed \
  duplicate_confidence=high \
  duplicate_rationale="<同じ問題、同じ修正方向、重複するファイルとコメント>"

Issueの場合:

prtags annotation issue set -R openclaw/openclaw <Issue番号> \
  duplicate_status=confirmed \
  duplicate_confidence=high \
  duplicate_rationale="<同じユーザーから見える問題と同じ意図された修正パス>"

グループの場合:

prtags annotation group set <グループID> \
  duplicate_confidence=high \
  cluster_summary="<1文の問題サマリー>" \
  duplicate_rationale="<これらのアイテムが1つの重複クラスタに属する理由>"

エビデンスが不完全な場合は、duplicate_status=candidateを設定し、信頼度を下げます。

PRごとまたはIssueごとの注釈書き込みがprtagsがターゲットを解決できないために失敗した場合、フォールバック書き込みパスを強制しないでください。 書き込み可能だったグループ状態を保持し、キュレーションバックエンドがまだターゲットオブジェクトを見つけられないことを報告し、そのアイテムの注釈を後で追加するために延期します。

ステップ 8: （オプション）手動GitHubコメントへのポスト

このステップはデフォルトでは実行しないでください。 メンテナーが明示的に指示した場合にのみ実行します。

prtagsの統合がGitHubコメント同期のために設定されていない場合、メンテナーはprtagsがGitHubにコメントを投稿するようにまだ設定されていないことを伝える軽量のコメントを投稿するよう指示する場合があります。

その場合:

gh pr comment <PR番号> --body "このPRは既存の作業の重複としてタグ付けされています（グループID: <ID>、信頼度: high）。`prtags`による自動コメントは現在設定されていません。"

重複解決コメント内で人々にタグ付けしたり、GitHubアクションをトリガーしたりしないでください。 ただ情報を提供するだけです。

メンテナーがコメントを投稿するよう指示していない場合は、このステップを完全にスキップします。

フォールバックルールとエラー処理

• ネットワークエラーが発生した場合は、停止し、エラーを報告します。リトライは自動的に行いません。
• 曖昧な発見があった場合は、判断を下そうとする前に停止し、メンテナーに要約を提示します。
• gitcrawlが応答しない、または利用できない場合（ビルド中、または別の理由による）は、ライブgh searchのみにフォールバックします。そのフォールバックをステップの出力に記録します。
• ghが応答しない、または認証されていない場合（これはよくあることです）、停止します。ghを動かそうとするハックは行いません。認証の問題を報告します。
• prtagsグループの作成または書き込みがベースオブジェクトの競合で失敗した場合は、競合するグループを検査します。グループをマージするための変更を報告しますが、メンテナーにマージを実行するよう依頼します。自動的にマージしないでください。