Cross-Ref: PR & Issue Linker

You find hidden connections between PRs and issues that humans miss at scale.
The core loop is: fetch → analyze in parallel → cluster → verify → report → act.

Before doing anything, read references/principles.md. Those rules override
everything in this file when there's a conflict.

Overview

Repos accumulate duplicate PRs and orphaned issue→PR links over time. Manual
cross-referencing doesn't scale past a few dozen items. This skill uses parallel
Sonnet subagents to analyze up to 1000 PRs and 1000 issues simultaneously,
finding two kinds of links:

1. 1. Duplicate PRs — PRs that address the same bug or feature (even with

different approaches or wording)

1. 2. Issue→PR links — Open issues that already have a PR solving them but

no explicit "fixes #N" reference

Results are grouped into thematic clusters, scored by actionability,
and presented with available actions (comment, close, label) — not just
as a flat list of pairs.

Configuration

The user provides these at invocation time (ask if not given):

Parameter	Default	Description
INLINECODE1	(ask)	GitHub owner/repo to analyze
INLINECODE3

1000 | How many recent PRs to scan |
| issue_count | 1000 | How many recent issues to scan |
| pr_state | all | PR state filter: open, closed, all |
| issue_state | open | Issue state filter: open, closed, all |
| batch_size | 50 | PRs per subagent batch |
| confidence_threshold | medium | Minimum confidence to include in report: low, medium, high |
| mode | plan | plan = report only (default, always start here). execute = act on findings. |

Default mode is plan (dry-run). The skill always starts by generating
the report. The user must explicitly choose to execute actions after reviewing
the findings. This matters because actions can't be undone.

Workflow

Phase 1: Data Collection

Fetch PR and issue metadata from the GitHub API. This phase is deterministic
and uses the shell script — no AI needed.

CODEBLOCK0

This produces:

• - workspace/prs.json — Full PR metadata
• INLINECODE27 — Full issue metadata (PRs filtered out)
• INLINECODE28 — Pre-extracted explicit cross-references
• INLINECODE29 — Compact one-line-per-PR index
• INLINECODE30 — Compact one-line-per-issue index

The existing references map captures what's already linked (via "fixes #N",
"closes #N", etc.) so subagents can focus on what's missing.

Phase 2: Parallel Analysis (Sonnet Subagents)

This is where the intelligence happens. Split PRs into batches and spawn
parallel Sonnet subagents. Each subagent receives:

• - Its batch of PRs (full metadata from prs.json, ~50 PRs)
• The complete issue index (compact, ~60KB)
• The complete PR index (compact, ~60KB) — for duplicate detection
• The existing references map (so it skips already-linked items)

Spawn subagents using the Task tool:

CODEBLOCK1

Subagent prompt template:

Important: When building each subagent prompt, paste the FULL contents of
references/principles.md into the "Decision Principles" section below.
Do not summarize or condense — include the complete text. This ensures
subagents always use the latest principles without drift.

CODEBLOCK2

Parallelism: Spawn ALL batch subagents simultaneously. With batch_size=50
and 1000 PRs, that's 20 parallel subagents. This is the power of the skill —
what would take hours sequentially completes in minutes.

Phase 3: Merge, Deduplicate & Cluster

After all subagents return:

1. 1. Collect all JSON results into a single array
2. Deduplicate duplicate_pr entries (A→B and B→A are the same link)
3. Merge confidence — if two subagents found the same link, take the

higher confidence and merge both evidence strings

1. 4. Filter by INLINECODE32
2. Build clusters — group related findings into thematic clusters (see below)
3. Score clusters by actionability (see below)
4. Sort clusters by score (highest first)

Save to workspace/results-unverified.json.

Clustering Algorithm

Instead of reporting isolated pairs, group connected findings into clusters.
Two findings belong to the same cluster if they share any PR or issue number.

Example: If you find PR#100 ↔ PR#101 (duplicate) and PR#100 ↔ Issue#50
(link), these form a single cluster: "Cluster: Issue#50 + PR#100 + PR#101".

Cluster structure:
CODEBLOCK3

The theme is a one-line summary that describes what this cluster is about
— the shared root cause or feature area. Generate it from the root_cause
fields of the cluster's findings.

Actionability Scoring

Each cluster gets a score based on these signals (clamp result to 0-10):

Signal	Points	Why it matters
All items open	+3	Can still be acted on
At least one high-confidence finding

+2 | Strong evidence |
| Multiple findings in cluster | +1 | More connections = more value |
| Issue has >5 reactions/comments | +1 | High community interest |
| PR is not draft | +1 | Ready for review |
| Cluster has a clear canonical PR | +1 | Easy to pick a winner |
| Any manual_review_required | -2 | Needs human judgment |
| All items closed | -3 | Low urgency |

Clusters scoring 7+ are actionable (green in report).
Clusters scoring 4-6 need review (yellow).
Clusters scoring 0-3 are low priority (gray).

Phase 3b: Evidence Verification

The batch subagents work from truncated bodies (500 chars) and compact indexes.
That's good enough for discovery but not for final decisions. This phase takes
the candidates and verifies them against deeper data.

Spawn a single verification subagent (Sonnet) that:

1. 1. Reads INLINECODE39
2. For each high/medium candidate, fetches deeper evidence via gh:

- Duplicate PRs: gh pr diff {id} --name-only for both PRs to confirm they actually touch the same files. If the file lists don't overlap at all, downgrade to low or remove. - Issue→PR links: gh issue view {id} --json body,comments to read the full issue body (not truncated) and check if any commenter already noted the connection. - For both: gh pr view {id} --json body to read the full PR body when the truncated version was ambiguous.

1. 3. For manual_review_required items: attempt to resolve with deeper data.

If still ambiguous after deep check, keep the flag — it goes to the user.

1. 4. Upgrades, downgrades, or removes candidates based on the deeper evidence.
2. Recalculates cluster scores after confidence changes.
3. Writes the verified results to workspace/results.json.

Verification subagent prompt:

CODEBLOCK4

This phase catches false positives that slipped through the discovery phase.
The batch subagents are optimized for recall (find everything plausible); the
verifier is optimized for precision (keep only what's real).

Skip this phase if the total candidate count is under 5 — the cost of
verification outweighs the benefit for small result sets.

Phase 4: Generate Report

Present the report to the user organized by clusters, not flat pairs.

Report structure:

CODEBLOCK5

Phase 4b: Suggested Actions Per Cluster

For each cluster, suggest appropriate actions based on confidence and item states.

For duplicate PRs (high confidence, both open):

1. 1. 💬 Comment — link the PRs so authors can coordinate
2. 🏷️ Label — add duplicate label to the weaker PR
3. ❌ Close — close the weaker PR as duplicate (only if very clear)

For duplicate PRs (one open, one closed):

1. 1. 💬 Comment — note the connection for context (lower priority)

For issue→PR links (high confidence):

1. 1. 💬 Comment on issue — note that a PR addresses this
2. 🏷️ Label issue — add has-pr or similar

For manual_review_required items:

1. 1. ⚠️ Flag for human — present in a separate section, no automated action

Action rules:

• - Never suggest closing without high confidence + verification
• Never suggest labeling without at least medium confidence
• Always suggest commenting as the minimum action (it's the safest)
• For clusters with mixed confidence, suggest the action matching the

lowest-confidence finding (conservative)

Phase 5: Interactive Action Strategy

After presenting the report, ask the user how they want to proceed.
Read references/commenting-strategy.md for rate-limiting details.

Present action choices per cluster:

For each actionable cluster, let the user pick:

• - Comment only — just link the items
• Comment + label — link and add labels
• Comment + close — link and close duplicates (high confidence only)
• Skip — do nothing for this cluster
• Manual — I'll handle this one myself

Then present the timing strategy. Read references/commenting-strategy.md for
the full tier definitions, rate calculations, and daily budget math. Present
the user with the strategy table from that file, populated with the actual
counts from the report. If total actions exceed the daily budget, show the
multi-day plan as described in commenting-strategy.md.

Always offer Dry Run (report only, no actions) as the default choice.
Also offer Skip — save the report but don't act at all.

Phase 6: Execute Actions

If the user chooses to act, build workspace/approved-comments.json and
execute with rate limiting via the shell script.

approved-comments.json schema (array of objects):

[
  {
    "target_number": 1234,
    "type": "issue_link|duplicate_pr",
    "body": "The full comment text to post",
    "cluster_id": 1,
    "finding_index": 0
  }
]

• - target_number — the issue or PR number to comment on (used by post-comments.sh)
• INLINECODE54 — finding type, used for logging only
• INLINECODE55 — the complete comment text
• INLINECODE56 and finding_index — traceability back to the report

CODEBLOCK7

For label and close actions, execute them inline (not via the script)
since they don't need the same rate limiting as comments:
CODEBLOCK8

Always execute in this order within a cluster:

1. 1. Post comments first (so the context exists before close/label)
2. Add labels
3. Close (only after comment is posted)

Comment style: Comments should feel like they're from a helpful maintainer,
not a bot. Vary the opener and closer for each comment to avoid sounding
repetitive. Always mention the PR author by name.

Comment templates (vary the opener each time):

Openers (rotate through these, never use the same one twice in a row):

• - "Heads up — this might be related."
• "Worth a look:"
• "Noticed a possible connection here."
• "This could be relevant to what you're working on."

For issue→PR links (comment on the issue):
CODEBLOCK9

For duplicate PRs (comment on the newer PR):
CODEBLOCK10

Every comment includes a correction path because wrong links erode trust.

Save progress to workspace/comment-progress.json for resume support.

Error Handling

• - API rate limit hit: Pause, show remaining reset time, save progress.
• Subagent returns invalid JSON: Log the error, skip that batch, warn user.

Don't retry — the batch results are lost but other batches continue.

• - PR/issue not found (deleted): Skip silently, note in report.
• Network error during commenting: Save progress immediately, offer resume.
• Subagent returns empty results: Normal — not every batch has links.
• Close/label fails: Log the error, continue with remaining actions.

Never retry a close — the user should investigate manually.

Workspace Structure

CODEBLOCK11

Resume Support

If a previous run exists in the workspace:

• - Phase 1-3: Skip if results.json exists and user confirms
• Phase 4: Skip if report.md exists and user confirms
• Phase 5-6: Resume from comment-progress.json if commenting was interrupted
• Ask: "Found a previous run with {N} results. Resume commenting or start fresh?"

Tips for Operators

• - Start with a smaller count (100 PRs, 100 issues) to validate before scaling
• Always review the report in plan mode before executing actions
• The compact index approach keeps memory usage manageable — don't fetch full

PR bodies (500 char truncation is intentional)

• - For very active repos (>10K PRs), increase batchsize to reduce subagent count
• Token costs: ~20 subagent calls for 1000 PRs at batchsize=50, each with

~120KB context. Plan accordingly.

• - The gh CLI token needs repo scope (private) or public_repo (public),

plus issues:write for posting comments.