# Git Issue Scoping > Read an issue's full comment thread and re-verify its cited evidence at HEAD. Use when scoping a PR or plan from a GitHub issue, or before filing or reversing one in your own tracker. - Skill: `laurigates/git-issue-scoping` (Agent Skill) - Install (CLI): `npx skillmds@latest add laurigates/git-issue-scoping` - Raw SKILL.md: https://api.skillmd.com/api/skills/laurigates/git-issue-scoping/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: laurigates (https://skillmd.com/u/laurigates) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/laurigates/git-issue-scoping --- # Git Issue Scoping Invoke before building a PR, plan, or prototype off a GitHub issue — including issues in repos you own, and before filing or reversing one in your own tracker. Before building a PR (or even an approach) off a GitHub issue, **read every comment in the thread** — not a fetched summary, not just the body. Issues that look like simple feature requests are often where the maintainer has already **converged on a specific design** with other experts. A summary compresses exactly the part that matters: the decided mechanism, the agreed scope, and the work someone has already volunteered to do. **Applies to repos you own too** (§ *Your own tracker*): the deference part is about upstream, but the load-bearing part is that a tracker records decisions past-you made and no longer remembers. ## The trap `WebFetch` (and any "summarize this issue" step) returns a *compressed* view. It faithfully captures the issue **body** and headline asks, but silently drops the back-and-forth in the comments where the real decisions live. You then design against the body's framing, build a prototype, and discover — only if you go back and read the comments — that: - the maintainer picked a **different mechanism** than the obvious one, - the **scope** (MUST / WANT / NICE / OUT) was explicitly bounded, - a dependency was **already prototyped** by a collaborator (and may be unreleased, so half your plan isn't even buildable yet), - your "open questions" were **already answered** in the thread — so asking them reads as not having done the homework. > Canonical break (jnv #114 → PR #116, 2026-06): a WebFetch summary presented the > issue as "extend completion beyond JSON paths." The actual 33-comment thread was > a design discussion in which the maintainer and the jaq author had converged on > **token-based segmentation** (jaq's `load::lex` token trees) plus a new `yield` > filter (an *unmerged* jaq PR) for the in-paren case, with an explicit scope > ladder. We built a byte-scanner PoC and a PR body that re-litigated settled > questions — caught only when the user asked "did we check all the comments?" > The PR had to be reframed before it was safe to surface. ## The rule When an issue is the basis for a contribution, read the comments **first**: ```sh gh issue view --repo / --json title,body,author,comments \ --jq '.body, (.comments[] | "--- " + .author.login + " ---\n" + .body)' ``` Specifically extract, before writing any code: 1. **Decided mechanism** — has the maintainer chosen an implementation approach? Build *that*, or explicitly propose an alternative knowing theirs exists. 2. **Scope ladder** — MUST / WANT / NICE / OUT. Don't attempt OUT; don't skip MUST. 3. **Dependencies in flight** — linked PRs/branches a collaborator is building. Check their state (`gh pr view` → merged? released?) before depending on them. 4. **Who's driving** — if the maintainer is mid-collaboration with another expert, a drive-by PR may duplicate their work. Ask whether a contribution is welcome *before* investing, and frame the PR as building on the thread, not restarting it. If you only have a summary and a gap has passed, **re-read the live thread** before acting — the discussion may have moved. ## A bot's recommendation is not a maintainer decision Point 1 above asks whether the maintainer chose an approach. The trap is that an automated triage comment **looks like** that choice. A `needs-decision` routine posts options A/B/C, adds its own **"I'd default to B"**, and closes with "reply here and the next run will implement the chosen option". Nothing has been decided. The recommendation is the bot's, and the reply it asks for is what would make it a decision. Read authorship and look for the reply, in the same call that fetches the thread: ```sh gh issue view --repo / --json comments --jq '.comments | length, (.[] | .author.login + " | " + (.body[0:80]))' ``` A single comment that is itself the request for a decision means the decision is **open**. Implement nothing that depends on it; ask the human, or say in the PR that you picked an option and which one. > Observed 2026-09-04 (`claude-plugins` #2441, #2568): two agents in one batch > independently read a `` comment's own > "I'd default to A" as the maintainer's choice and wrote it into their PR > bodies as settled. Both issues carried **exactly one comment** — that request > — with no reply, no reactions, and no review. On #2441 the routine had > recommended B, the agent shipped A, and the human's actual answer was B, so > the PR was built on the wrong option *and* cited an authority that did not > exist. Caught by an independent verifier running `--jq '.comments | length'`. Two consequences worth separating: - **`Closes #N` on an undecided issue** auto-closes the decision when the PR merges. Use `Refs #N` until the option is chosen. - **A false attribution is load-bearing.** On #2568 it was the *only* cited grounds for rejecting a reviewer's finding, so the finding had to be re-examined once the attribution collapsed. Never cite a decision you have not read; when you chose the option yourself, say so plainly. ## Your own tracker — search before filing, read before reversing No maintainer to defer to is exactly why this gets skipped. Two failures: 1. **Search before filing** — a well-researched duplicate is still a duplicate, and the better write-up makes it *harder* to spot as one. `gh issue list -R / --state all --search "" --json number,title,state` 2. **Read before reversing** — an old issue records not just a problem but a *decision with its reasoning*, including decisions to **defer**. Shipping the deferred option because it is obviously better silently overrides a choice made with context you no longer have. > Observed 2026-08 (pal-mcp-server), ten minutes apart: filed a detailed issue > duplicating a month-old one that had already diagnosed the same broken publish > pipeline — then merged a PR doing the very migration that issue **explicitly > deferred**. Neither was caught by review; both surfaced only from listing open > issues afterwards. The tell: calling something "the obvious fix" on a subsystem broken long enough for someone to have written about it — long-broken means *investigated*. When reversing a decision, say so on the PR and issue, quoting the old reasoning, so the next reader sees a decision changed rather than forgotten. ## An issue's cited evidence expires — re-verify every line before acting on it Distinct from the sections above, which are about *discussion* you failed to read. Here you read everything, and the issue is simply **out of date**: it cites `file.ts:230` and asserts what is there, and between filing and today some unrelated PR fixed it. A well-written issue makes this worse — precise line numbers and quoted snippets read as verified fact, and the better the write-up, the less anyone re-checks it. > Observed 2026-08-13 (thelma #1055). A security issue's central claim was > "no `responseSchema` enforcement on the Gemini call — `gemini.ts:230` does > not pass it." True when filed on 05-13; false by the time it was worked. > #1060 had added it in between. The issue even listed *"`responseSchema` > enforcement is deliberately removed (currently absent)"* as a trigger to > re-evaluate — so writing the doc from the issue verbatim would have shipped > a threat model asserting the absence of the control that was by then its > primary defence, and inverted one of its own triggers. - **Re-read every file:line the issue cites, at HEAD, before writing anything from it.** The issue is a *claim about the code*, and the code is the authority — same instinct as `diagnose-at-the-failure-point.md`. - **Date the gap.** `gh issue view --json createdAt` against `git log -S'' -- ` finds the PR that moved it. An issue older than a few weeks on an active file should be assumed stale until checked. - **Report the correction in the PR that acts on it**, so the next reader sees the issue's evidence was superseded rather than silently contradicted. - Corollary for *filing*: prefer citing behaviour and symbols over line numbers, which rot fastest. ## When it bites - Any external contribution scoped from an issue, especially a popular repo where maintainers discuss design in comments. - **Acting on an issue filed weeks or months ago against a file that has since changed** — the evidence is stale even though the thread is complete. - **Your own repo**, when the tracker is the last place you think to look. - Resuming work on an issue days later from a cached summary. - Letting an early `WebFetch`/research step stand in for the primary source. ## Related - `~/.claude/rules/verify-upstream-before-patching.md` — same instinct (check the authoritative source before acting) for vendored code; this is the issue-thread analogue. - `~/.claude/rules/tool-use-patterns.md` (WebFetch) — a summary is lossy; for a decision that gates real work, go to the full source, not the fetched digest. - `git-plugin:git-issue` — the consumer: the end-to-end issue→PR workflow that scopes from the issue thread this skill teaches you to read in full. ## Rationale The cost asymmetry is stark: reading the thread is one `gh issue view` and a few minutes; skipping it costs a misaligned prototype, a PR that signals you didn't read the discussion, and a reframe-or-close under the maintainer's eye. The full thread is the spec; the summary is a lossy proxy for it.