diff --git a/.agents/skills/tag-duplicate-prs-issues/SKILL.md b/.agents/skills/tag-duplicate-prs-issues/SKILL.md new file mode 100644 index 00000000000..0c5e3a7ba95 --- /dev/null +++ b/.agents/skills/tag-duplicate-prs-issues/SKILL.md @@ -0,0 +1,437 @@ +--- +name: tag-duplicate-prs-issues +description: Maintainer workflow for deciding whether an OpenClaw pull request or issue is a duplicate, gathering evidence with ghreplica and pr-search-cli, grouping related work in prtags, and syncing the duplicate grouping back to GitHub through prtags. Use when Codex needs to search for duplicate PRs or issues, create or reuse a duplicate group, enforce one-group-per-target discipline, save duplicate judgments in prtags, or prepare group state for comment sync. +--- + +# Tag Duplicate PRs and Issues + +Use this skill when a maintainer needs to decide whether a pull request or issue is a duplicate of existing work. + +This skill is for maintainer triage and grouping. +It is not for reviewing the implementation quality of a PR. + +## Required Setup + +Do not start duplicate triage until this setup is complete. + +### Install the companion skills + +Install these skills first because they teach the agent how to use the two main CLIs correctly: + +- `ghreplica` skill from the `ghreplica` repo at `skills/ghreplica/SKILL.md` +- `prtags` skill from the `prtags` repo at `skills/prtags/SKILL.md` + +This skill assumes those two skills are available and can be used during the same run. + +### Install the CLIs + +Install `ghreplica` and `prtags` from their latest GitHub releases. +Do not rely on an old local build unless the maintainer explicitly wants to test unreleased behavior. + +`ghreplica` CLI install path: + +```bash +curl -fsSL https://raw.githubusercontent.com/dutifuldev/ghreplica/main/scripts/install-ghr.sh | bash -s -- --bin-dir "$HOME/.local/bin" +``` + +`prtags` CLI install path: + +```bash +curl -fsSL https://raw.githubusercontent.com/dutifuldev/prtags/main/scripts/install-prtags.sh | bash -s -- --bin-dir "$HOME/.local/bin" +``` + +Use the `pr-search-cli` project with `uvx`. +The command itself is `pr-search`. +Do not require a permanent install unless the maintainer explicitly wants one. + +```bash +uvx --from pr-search-cli pr-search status +uvx --from pr-search-cli pr-search code similar 67144 +``` + +### Authenticate prtags + +`prtags` should be logged in with the maintainer's own GitHub account through OAuth device flow. +Do not use a shared maintainer token for interactive triage. + +```bash +prtags auth login +prtags auth status +``` + +The expected outcome is that `prtags` stores the logged-in maintainer identity locally and uses that account for authenticated writes. + +### Verify the tools before triage + +Before using this skill, make sure all three tools are available: + +```bash +ghr repo view openclaw/openclaw +prtags auth status +uvx --from pr-search-cli pr-search status +``` + +## Goal + +For each target PR or issue: + +1. gather duplicate evidence +2. decide whether it is a real duplicate +3. create or reuse one `prtags` group for that duplicate cluster +4. save the maintainer judgment in `prtags` +5. rely on normal `prtags` group writes to drive GitHub comment sync when that integration is configured + +## Tool Roles + +Use the tools with these boundaries: + +- `ghreplica` is the raw evidence source + - use it for title/body/comment search, related PRs, overlapping files, overlapping ranges, and current PR or issue status +- `pr-search-cli` is candidate generation and ranking + - use it to suggest likely duplicate PRs or issue-cluster context + - do not treat it as final truth +- `prtags` is the maintainer curation layer + - use it to create or reuse one duplicate group + - use it to save the duplicate status, confidence, rationale, and group summary + - use it as the source of truth for the GitHub-facing group comment + +## Working Rules + +- Do not call something a duplicate only because the titles are similar. +- Do not call something a duplicate only because the same files changed. +- A duplicate cluster should be based on the same user-facing problem, the same intent, and substantially overlapping implementation or investigation context. + +## One-Group Rule + +Treat duplicate groups as exclusive. +A PR or issue should belong to at most one duplicate group at a time. + +That means: + +- before creating a new group, search for an existing group that already represents the same duplicate story +- if the target already appears to belong to a different duplicate group, stop and resolve that conflict first +- do not create a second group for the same target just because the wording is slightly different +- if two plausible existing groups overlap and you cannot safely merge the judgment, stop and ask the maintainer + +This rule matters more than speed. +The skill should keep one coherent duplicate cluster per problem, not many near-duplicate clusters. + +## What A Good Duplicate Group Represents + +A duplicate group should describe the underlying problem and the intended fix direction. +Do not group items only because they share a keyword. + +Good group shape: + +- same user-facing bug or same maintainer-facing task +- same subsystem or code surface +- same intended change direction +- same likely duplicate-resolution path + +Bad group shape: + +- “all PRs that touch Slack” +- “all issues mentioning retry” +- “all auth-related items” + +The group title should name the real problem. +The group description should summarize the intent and the code surface. + +Examples: + +- `gateway: startup regression from channel status bootstrap` +- `whatsapp: QR preflight timeout handling` +- `release: cross-OS validation handoff gaps` + +## Evidence Checklist + +Before declaring a duplicate, gather evidence from at least two categories. + +For PRs: + +- same or nearly same problem statement +- same changed files or overlapping file ranges +- same fix direction +- same subsystem and failure mode +- same linked issue or same user-visible symptom + +For issues: + +- same user-visible problem +- same reproduction story or same failure mode +- same likely fix area +- same PRs already linked or discussed +- same maintainers already steering toward the same duplicate grouping + +If you only have wording similarity, that is not enough. + +## Step 1: Read The Target + +Start by reading the target itself. + +For a PR: + +```bash +ghr pr view -R openclaw/openclaw --comments +ghr pr reviews -R openclaw/openclaw +ghr pr comments -R openclaw/openclaw +``` + +For an issue: + +```bash +ghr issue view -R openclaw/openclaw --comments +ghr issue comments -R openclaw/openclaw +``` + +Record: + +- target type and number +- title +- problem statement +- proposed intent +- subsystem +- whether it is open, closed, or merged +- whether there is already a likely duplicate thread mentioned by humans + +## Step 2: Search Broadly With ghreplica + +Use `ghreplica` first because it is the most direct evidence source. + +### PR duplicate search + +Run all of these when the target is a PR: + +```bash +ghr search related-prs -R openclaw/openclaw --mode path_overlap --state all +ghr search related-prs -R openclaw/openclaw --mode range_overlap --state all +ghr search mentions -R openclaw/openclaw --query "" --mode fts --scope pull_requests --state all +ghr search mentions -R openclaw/openclaw --query "" --mode fts --scope issues --state all +``` + +Use `prs-by-paths` or `prs-by-ranges` when the likely duplicate surface is already known: + +```bash +ghr search prs-by-paths -R openclaw/openclaw --path src/example.ts --state all +ghr search prs-by-ranges -R openclaw/openclaw --path src/example.ts --start 20 --end 80 --state all +``` + +### Issue duplicate search + +`ghreplica` does not have a special issue-to-issue “related issues” command. +For issues, search mirrored text and linked PR context instead. + +Run targeted text searches: + +```bash +ghr search mentions -R openclaw/openclaw --query "" --mode fts --scope issues --state all +ghr search mentions -R openclaw/openclaw --query "" --mode fts --scope issues --state all +ghr search mentions -R openclaw/openclaw --query "" --mode fts --scope pull_requests --state all +``` + +Then inspect the candidate PRs or issues those searches uncover. + +## Step 3: Use pr-search-cli As A Hint Layer + +Use `pr-search-cli` after `ghreplica`. +It is good at surfacing candidates quickly, but it is not the final decision-maker. +Run it through the `pr-search` command. + +For a PR: + +```bash +uvx --from pr-search-cli pr-search -R openclaw/openclaw code similar +uvx --from pr-search-cli pr-search -R openclaw/openclaw code clusters for-pr +uvx --from pr-search-cli pr-search -R openclaw/openclaw issues for-pr +uvx --from pr-search-cli pr-search -R openclaw/openclaw issues duplicate-prs +``` + +Interpretation: + +- `code similar` suggests PRs with similar change shape +- `code clusters for-pr` shows the PR’s nearby code cluster +- `issues for-pr` shows which issue clusters the PR appears to belong to +- `issues duplicate-prs` is useful for spotting already-known duplicate PR patterns + +For an issue: + +- use `ghreplica` first to find candidate PRs or issue wording +- if the issue has linked PRs or a likely implementation PR, run `pr-search-cli` on those PRs +- treat issue-cluster output as supporting context, not as enough by itself to call the issue a duplicate + +## Step 4: Decide The Outcome + +Choose one of these outcomes: + +- `not_duplicate` +- `duplicate_needs_judgment` +- `duplicate_confirmed` + +Use `duplicate_confirmed` only when the evidence is strong enough that the maintainer could safely close or retag the duplicate item. + +Use `duplicate_needs_judgment` when: + +- the problem looks the same but the implementation goal differs +- the code overlap is weak +- the issue wording is ambiguous +- there may be two valid duplicate group interpretations +- the target appears to intersect two existing duplicate groups + +## Step 5: Reuse Or Create One prtags Group + +Before creating a group, search `prtags` for an existing one. + +Start with text search over groups: + +```bash +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 +``` + +Inspect likely groups: + +```bash +prtags group get +prtags group get --include-metadata +``` + +Reuse an existing group when: + +- it represents the same problem +- it already contains clearly related members +- adding the target would keep the group coherent + +Create a new group only when no existing group clearly fits. + +Create the group with a problem-based title and an intent-based description: + +```bash +prtags group create -R openclaw/openclaw \ + --kind mixed \ + --title "" \ + --description "" \ + --status open +``` + +Then attach the target and any known duplicate members: + +```bash +prtags group add-pr +prtags group add-issue +``` + +If a target appears to already belong to another duplicate group and you cannot safely reuse that group, stop. +Do not create a second group. + +## Step 6: Ensure The Annotation Fields Exist + +Use `field ensure` so the skill is idempotent. + +Recommended target-level fields: + +```bash +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 +``` + +Recommended group-level fields: + +```bash +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 +``` + +## Step 7: Save The Maintainer Judgment In prtags + +For a PR: + +```bash +prtags annotation pr set -R openclaw/openclaw \ + duplicate_status=confirmed \ + duplicate_confidence=high \ + duplicate_rationale="" +``` + +For an issue: + +```bash +prtags annotation issue set -R openclaw/openclaw \ + duplicate_status=confirmed \ + duplicate_confidence=high \ + duplicate_rationale="" +``` + +For the group: + +```bash +prtags annotation group set \ + duplicate_confidence=high \ + cluster_summary="" \ + duplicate_rationale="" +``` + +When the evidence is incomplete, set `duplicate_status=candidate` and lower the confidence. + +## Step 8: Let prtags Sync The Group Comment + +Do not tell the agent to create a GitHub comment directly. +`prtags` owns the outbound GitHub comment as a derived projection of group state. + +In the normal case, do not manually trigger comment sync. +When comment sync is configured, group writes already enqueue the derived comment projection automatically. + +Use manual sync only as a repair or retry path: + +```bash +prtags group sync-comments +``` + +If the maintainer needs to see which groups still need attention, use: + +```bash +prtags group list-comment-sync-targets -R openclaw/openclaw +``` + +The skill should treat the GitHub comment as a consequence of correct `prtags` group state. +It should not treat manual comment authoring as part of the normal duplicate workflow. +It should also not treat `sync-comments` as a required step for every duplicate decision. + +## Output Format + +Return a short maintainer report with these sections: + +```text +Decision: duplicate_confirmed | duplicate_needs_judgment | not_duplicate +Target: PR # | Issue # +Confidence: high | medium | low + +Evidence: +- ... +- ... +- ... + +prtags actions: +- reused group | created group +- added members: ... +- annotations written: ... +- comment sync: automatic if configured | manual repair triggered for +``` + +## Stop Conditions + +Stop and escalate instead of forcing a duplicate decision when: + +- the target appears to belong to two different duplicate groups +- the duplicate grouping is unclear +- the wording matches but the implementation goals differ +- two PRs touch the same files for different reasons +- two issues describe similar symptoms but likely different root causes + +The maintainer should get one clean duplicate judgment or an explicit “needs judgment” result. +Do not blur the line. diff --git a/.agents/skills/tag-duplicate-prs-issues/agents/openai.yaml b/.agents/skills/tag-duplicate-prs-issues/agents/openai.yaml new file mode 100644 index 00000000000..357999a60ba --- /dev/null +++ b/.agents/skills/tag-duplicate-prs-issues/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Tag Duplicate PRs and Issues" + short_description: "Find duplicate PRs and issues, group them in prtags, and let prtags sync the GitHub comment" + default_prompt: "Use $tag-duplicate-prs-issues to decide whether an OpenClaw PR or issue is a duplicate, gather evidence with ghreplica and pr-search-cli, group related items in prtags, and save the duplicate judgment."