garrytan / garrytan/gstack

feat(pr-prep): audit an issue you are about to file, not just commits

Open
#2,642 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
133k
Forks
19.9k
Avg merge
18h 46m
Merged PRs (30d)
26

Description

### Context — this builds on #1696, which is still open

`/pr-prep` is a pre-PR upstream duplicate audit: it walks `git log base..HEAD`, derives search keywords from commit subjects and changed paths, queries upstream issues and PRs via `gh`, scores each commit for collisions (EXACT_DUP / OVERLAP / SIBLING / CLEAN), and blocks on a hard duplicate. It hooks into `/ship` as a Step 1.5 gate.

It arrived as #1696, opened 2026-05-25 and still open. The skill is not on `main` — nothing in `pr-prep/`, no mention in `ship/SKILL.md` — so everything below describes a gap in code that has not landed yet.

Filing it here rather than sitting on it, so the gap is on the record and travels with the skill if it lands.

### What's missing

`pr-prep` already searches upstream issues as duplicate candidates — Step 3 fires `gh issue list` for open and recently-closed, and an open issue carries 0.7× weight in the collision score. But the unit of audit is always a **commit**, and the gate is always `gh pr create`.

There is no mode for auditing an **issue you are about to file**. Nothing derives search keywords from a document, and the `/ship` integration is PR-only.

The half that already works: `--repo owner/name` points the Step 3 queries at any repo, and `bin/gstack-pr-prep-score` is a pure function over a candidate set that does not care where the candidates came from.

### Why it matters

Duplicate issues cost the same triage attention as duplicate PRs, and they are cheaper to file, so trackers accumulate more of them. A crowded tracker is exactly where the audit pays off.

Concrete case, 2026-08-20. Filing a Claude Code bug report (`anthropics/claude-code#88113`) turned up `anthropics/claude-code#66279`, titled "Project-scope permission grant strips unknown top-level keys from `.claude/settings.json`" — a near-match to the intended headline. Reading it showed a different bug: known schema keys at the root of a project settings file, versus unknown keys nested inside hooks in user settings, where root-level keys demonstrably survive. Four more siblings turned up in the same sweep.

Without that sweep the report would have been filed with no reference to any of them, and a triage pass matching on title alone would reasonably have closed it as a duplicate of #66279.

The audit was run by hand: Step 3's fetch loop with `--repo anthropics/claude-code` and keywords typed in from the report. Steps 4.4, 4.5 and 4.6 (codex second opinion, CONTRIBUTING pre-push gates, commit-message conformance) are dead weight when there is no commit.

### Proposed shape

An issue mode that reuses the existing machinery rather than forking it.

```
/pr-prep --issue [--title "..."] --repo owner/name
```

- **Keyword extraction** — from the title plus section headings and the first paragraph, using the same stop-word and verb-stripping rules Step 2 applies to commit subjects. Same 3-6 token cap; the cap is the part that makes Step 3 work.
- **Step 3 unchanged** — same four fetches, same `gstack-issue-guard` envelope, same "(empty body) means zero matches, no envelope means the pipeline failed" health signal.
- **Step 4 unchanged** — same `bin/gstack-pr-prep-score`. Title Jaccard applies as-is. File overlap does not (there are no changed files), so the file-overlap term should drop out of the score rather than count as zero, which would otherwise depress every hit below threshold.
- **Skip** Steps 4.4 / 4.5 / 4.6 — they are commit-shaped.
- **Buckets** keep their meaning, with EXACT_DUP reading as "this issue is already filed, comment there instead" rather than "close your PR".
- **Output** the same JSON shape to `/tmp/ship-pr-prep.json`, so anything reading it keeps working.

### Open questions

- Should EXACT_DUP refuse, the way the PR path does? Filing a duplicate issue is cheaper to undo than filing a duplicate PR, so a loud report may be the better default and `--force` may be unnecessary.
- Worth auto-appending a "Related issues" section to the body from the SIBLING/OVERLAP hits? That was the single highest-value output in the real case, and it was assembled by hand.
- Issue templates: `anthropics/claude-code` has a 13-field `bug_report.yml`, and a body that ignores the template lands outside normal triage. Detecting `.github/ISSUE_TEMPLATE/*.yml` and reporting the required fields would fit naturally alongside the existing Step 1.4 `CONTRIBUTING.md` read.

### Happy to build it — after a steer on #1696

I would be glad to build this on top of the functionality in #1696, either folded into that PR or as a follow-up, whichever suits you.

I would rather not start until there is a direction on #1696 itself: whether you want `/pr-prep` in gstack at all, and if so what shape it should take to land. It has been open since May without a review, so I have no read on whether the approach is one you want, whether it needs reworking, or whether it is not a fit for the project. Any of those three answers is genuinely useful to me — a "no thanks" costs me nothing and saves me from building more on top of it.

Adding issue mode would grow the surface further, so it seems better to ask for that steer first than to keep extending a PR that may not be the direction you want.

### Duplicate check

Ran against `garrytan/gstack`: queries `pr-prep issue mode`, `duplicate audit issue`, `pr-prep`. No open or closed issue covers this, and nothing in `TODOS.md`. CLEAN.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing #1696 and the proposed /pr-prep flow, then inspect the referenced bin/gstack-pr-prep-score and the /tmp/ship-pr-prep.json contract. Confirm how Step 3 queries and Step 4 scoring are reused for issue bodies, and resolve the listed open questions; done means an agreed issue mode that preserves the existing JSON output and /ship compatibility.

Written by the indexing model from the issue text.

Assessment

Tech stack
git, github, typescript
Domain
cli, developer-experience, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.