tag-duplicate-prs-issues

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# 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 write duplicate groups or annotations until this setup is complete.
Read-only discovery can still proceed with `gitcrawl` and live `gh`.

### Companion Skills

Use `$gitcrawl` first for local candidate discovery.
Use the `prtags` skill from the `prtags` repo at `skills/prtags/SKILL.md` when it is available.

### Install the CLIs

Install `prtags` from its latest GitHub release.
Do not rely on an old local build unless the maintainer explicitly wants to test unreleased behavior.

`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"
```

### 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.

## Missing-Setup Rule

Do not require an up-front preflight before starting the workflow.
Proceed with the normal steps until you actually need a tool or account state.

As soon as you discover that `prtags` is missing or not logged in at the write step, stop immediately.
Do not continue in a partial write mode after that point.

If `prtags` is missing, ask the user to run:

```bash
curl -fsSL https://raw.githubusercontent.com/dutifuldev/prtags/main/scripts/install-prtags.sh | bash -s -- --bin-dir "$HOME/.local/bin"
```

If `prtags auth status` shows that the user is not logged in, ask the user to run:

```bash
prtags auth login
```

Resume only after the missing tool or login state has been fixed.

## Read-Path Default

For candidate discovery in this workflow, use `gitcrawl` first.
Treat it as the local history and clustering layer for related issues, duplicate attempts, and closed threads.

Use live `gh` or `gh api` for the target thread and for any candidate before making an actionable judgment.
Use live GitHub when `gitcrawl` is missing or stale for a concrete reason, such as:

- the target or candidate is not present yet
- the local data is clearly stale or incomplete for the decision you need to make
- `gitcrawl` errors, times out, or lacks the needed neighbor/search data

When you fall back to live GitHub search, note that you did so and why.

If a later `prtags` target-level write fails because its own mirror has not caught up, stop and report that the curation backend is missing the target object instead of forcing a fallback write.

## 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:

- `gitcrawl` is candidate generation and historical context
  - use it first for local title/body search, neighbors, clusters, and closed-thread discovery
  - treat every candidate as a lead until live GitHub confirms it
- `gh` is live GitHub truth
  - use it for target state, body, comments, reviews, files, linked issues, and current open/closed/merged status
  - use `gh search` only when `gitcrawl` is stale, missing data, or cannot express the needed query
- `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

From liuda1999/Quiet-Core-bot, MIT.

More from liuda1999/Quiet-Core-bot