# Pr Precheck

> Use when the user invokes `/pr-precheck <repo> <topic>` or — implicitly, before any other skill opens a pull request — to check the target repo's merged and closed PR history for prior attempts at the same fix, so the agent doesn't open the Nth duplicate of an already-rejected approach. Wraps the `vouch pr-cache` CLI (build / check / show) and turns its verdict into a clear stop / ask / proceed s…

- **Type:** Skill
- **Install:** `agentstack add skill-vouchdev-vouch-pr-precheck`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [vouchdev](https://agentstack.voostack.com/s/vouchdev)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [vouchdev](https://github.com/vouchdev)
- **Source:** https://github.com/vouchdev/vouch/tree/main/skills/pr-precheck
- **Website:** https://vouchai.dev

## Install

```sh
agentstack add skill-vouchdev-vouch-pr-precheck
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# PR Precheck

**Goal:** before you raise a PR, find out whether someone already tried this fix — especially whether anyone tried and got *rejected*. The cost of asking is seconds; the cost of a duplicate PR is reviewer attention, contributor reputation, and (on Bittensor-style mining repos) wasted scoring weight.

This skill is a thin orchestration layer over the `vouch pr-cache` CLI shipped in vouch ≥ this PR. It's safe to invoke directly **and** to chain ahead of `pr-fix` / `prs-auto`.

## Invocation

Direct:

```
/pr-precheck  
/pr-precheck   --files a.py,b.py
```

Implicit (auto-fires inside `pr-fix` / `prs-auto` before the "open PR" step):

```
/pr-fix https://github.com/owner/repo/issues/N
   └─ before pushing the branch, run pr-precheck on the planned PR title + files
```

`` may be:

- `https://github.com//`
- `git@github.com:/.git`
- `/` (shorthand)

`` is the title-like phrase that describes the PR you're about to raise. Be specific — short generic strings ("fix bug") will match too many cached PRs.

## Prerequisites

- **`vouch` CLI** on `PATH` (`pip install vouch-kb` ≥ the version that ships `pr-cache`).
- **`gh` CLI** authenticated for the target repo's read scope (`gh auth status` returns a session).
- *Optional:* `claude` CLI on `PATH` **or** `ANTHROPIC_API_KEY` in env — only needed if you pass `--analyze-closed` and want LLM-summarised "why was this closed" notes attached to each closed PR record.

If `vouch` is missing, **stop and tell the user**. Don't fall back to manual `gh` queries — the whole value of this skill is the cached, ranked, dedup-aware view.

## Step 1 — Ensure cache is present and fresh

The cache lives at `~/.cache/vouch/pr-cache/__.json`. Build it if missing, or if it's older than 24 h, or if the user passes `--rebuild`.

```bash
CACHE=~/.cache/vouch/pr-cache/${OWNER}__${REPO}.json
if [ ! -f "$CACHE" ] || [ "$(find "$CACHE" -mmin +1440 -print 2>/dev/null)" ]; then
  vouch pr-cache build "$REPO_URL" --state all --limit 200
fi
```

For repos with > 200 PRs per state, bump `--limit` (the cap is gh API rate limit, not vouch). If the target repo has a known cluster of duplicate-prone areas (e.g. Bittensor mining repos), prefer `--analyze-closed` once so closed-PR rejection reasons are cached for future runs:

```bash
vouch pr-cache build "$REPO_URL" --analyze-closed
```

This calls the local `claude` CLI per closed PR (no API key needed) — slow on the first run, cheap on every subsequent `check` because the analysis is persisted.

## Step 2 — Run the check

```bash
vouch pr-cache check "$REPO" \
  --topic "$TOPIC" \
  ${FILES:+--files "$FILES"} \
  --top-k 5
```

Output is JSON with shape:

```json
{
  "verdict": "likely_duplicate" | "review_candidates" | "no_match",
  "cache_size": 335,
  "candidates": [
    {
      "number": 1419,
      "state": "closed",
      "title": "...",
      "url": "...",
      "score": 0.6,
      "title_overlap": 0.6,
      "path_overlap": 0.0,
      "close_analysis": { "reason": "...", "do_not_repeat": [...] } | null
    }
  ]
}
```

Score is 0..1 — overlap coefficient on title+body tokens, optionally blended with file-path Jaccard when `--files` is passed. Closed-not-merged PRs outrank merged ones on score ties (the "this was rejected before" signal is the higher-value one).

## Step 3 — Branch on the verdict

| Verdict | Score range | What you do |
|---------|-------------|-------------|
| `likely_duplicate` | top score ≥ 0.70 | **Stop.** Surface the top 3 candidates to the user with their titles, states, URLs, and any cached `close_analysis.reason` / `do_not_repeat` bullets. Ask: "Open anyway, fold this into one of those, or skip?" |
| `review_candidates` | any candidate ≥ 0.15, top ",
  "candidates": [ ... ]
}
```

## Failure modes

| Symptom | Cause | Action |
|---------|-------|--------|
| `vouch: command not found` | vouch not installed | Tell the user. Do not fall back to manual gh queries. |
| `Error: ... gh ... not found` | gh CLI missing | Tell the user. |
| `Error: gh exited 4: HTTP 401` | gh not authenticated for that repo | Run `gh auth status`; ask the user to authenticate. |
| `verdict: no_match` on a repo you just contributed to | Cache stale (last build pre-dates your other PRs) | Rerun with `--rebuild`. |
| Many false positives at score 0.50–0.65 | Topic is too generic ("fix bug", "refactor") | Re-ask with a sharper topic that uses domain-specific nouns (filenames, class names, error strings). |

## Why this exists

Validated against `entrius/gittensor` (Bittensor SN74 / Gittensor): one `vouch pr-cache check` against the topic `"normalize github_id to str for miner matching"` surfaced **four** closed-not-merged PRs (#1414, #1416, #1417, #1419), all attempting the same fix, all rejected. Without this skill, the fifth contributor would have opened the fifth duplicate. With it, that contributor sees the wreckage in seconds and decides whether to:

1. Read the rejection comments and pick a different approach.
2. Pick up one of the existing closed PRs and address its review.
3. Confirm the prior PRs are genuinely unrelated and proceed.

All three of those are wins; opening duplicate #5 is the only loss.

## Integration hook for `pr-fix` / `prs-auto`

When this skill is invoked as a sub-step (not directly by the user), it should:

1. **Not** ask the user before running — it's part of the parent workflow.
2. Run with the parent's planned PR title as `--topic` and the planned changed files as `--files`.
3. Return its verdict; the parent decides whether to halt + escalate to the user or proceed silently.
4. On `likely_duplicate`, the parent **must** stop and surface, even if the user originally said "just go".

A simple parent-side gate:

```bash
PRECHECK=$(claude run /pr-precheck "$REPO" "$TITLE" --files "$FILES" --as-data)
case "$(echo "$PRECHECK" | jq -r .verdict)" in
  likely_duplicate)  echo "$PRECHECK" | jq -r .human_summary; exit 0 ;;
  review_candidates) echo "$PRECHECK" | jq -r .human_summary; read -p "proceed? " yn; [ "$yn" = y ] || exit 0 ;;
  no_match)          : ;;  # proceed
esac
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [vouchdev](https://github.com/vouchdev)
- **Source:** [vouchdev/vouch](https://github.com/vouchdev/vouch)
- **License:** MIT
- **Homepage:** https://vouchai.dev

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-vouchdev-vouch-pr-precheck
- Seller: https://agentstack.voostack.com/s/vouchdev
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.