/issue-brief

name: issue-brief
description: Explain a GitHub issue, discussion, or feature request in plain language before deciding whether to build it. Covers what the reporter actually wants, a numbered walkthrough of the failure using real hostnames/ports/endpoints, how the code behaves today with file:line anchors, what implementing it would take, and the traps (security regressions, open PRs touching the same files, older issues with the same root cause). Use whenever a github.com issues/ or discussions/ link is pasted, or the user says check / look at / verify / assess / analyse this issue, what does this issue want, is it worth doing, what would it take, or refers to one by number (issue 198, discussion 49). Also handles the follow-ups "what are the cons" and "explain that in simple terms". NOT for pull requests (use /review) and NOT for implementing. An issue-brief ends with the working tree untouched.

issue-brief — explain an issue before building it

The output is an **explanation**, not a design doc and not a diff. Assume the reader has not read the reporter's post and does not have the file layout in their head. Lead with the plain meaning; the architecture comes fourth.

1. Fetch the thing

Issues:

gh issue view <number-or-url> --json number,title,state,author,createdAt,closedAt,labels,body,comments

**Discussions need GraphQL.** There is no `gh discussion` command (verified on gh 2.92), and `gh issue view` will not resolve a discussion number. Use:

gh api graphql -f query='
{ repository(owner:"VasiHemanth", name:"tokentelemetry") {
    discussion(number: NNN) {
      number title url category{name} author{login} createdAt body
      comments(first:20){ nodes { author{login} body } }
    } } }'

Then, before writing anything:

• **Check it isn't already done.** Grep the codebase for the feature's nouns.

Issue 135 (Pi agent support) was closed and fully shipped; the tell was `PI_SESSIONS_DIR` and `test_pi_scan.py` already sitting on main.

• **Search for the same root cause elsewhere**, open and closed

(`gh issue list --search`). Issues 198 and 96 were the same two-port problem reported twice, a year apart, by different people.

• **Check open PRs that touch the files you'd touch** (`gh pr list`). They set

the landing order.

2. Answer in this order

1. **What the reporter actually wants**, in one or two sentences of plain language, jargon stripped. Name them. Link the earlier issue or PR if it's a repeat. 2. **A concrete walkthrough of the problem.** Pick one realistic setup and trace it as numbered steps, with real hostnames, real ports, real endpoints. Never "suppose a user does X". Say what the user *sees* first, then why it happens. 3. **How it works today**, only the part that bears on the issue, with `file.py:line` anchors so the claim can be checked. 4. **What implementing it would take**: the shape of the change and which layer it belongs in, not a full diff. 5. **Traps and interactions.** Security regressions, open PRs on the same files, closed issues with the same root cause, what has to land first. 6. **A verdict and one next step** ("worth accepting, want me to draft the reply comment?").

Steps 3 and 4 collapse to a sentence each when the issue is simple. Steps 1, 2 and 6 are never skipped.

3. Prose rules

• **Symptom before mechanism.** "It looks broken but nothing crashed, the page

just never got its data," and only then the middleware ordering.

• **Expand every acronym and product name once**, the first time it appears.

The reporter's Pangolin / SSE / CORS gets one clause of explanation.

• **Don't paste code blocks.** Quote a few lines at most, or cite `file:line`

and let the reader open it.

• **No hedging stacks.** One verdict. If it is genuinely balanced, say what

evidence would decide it.

• **Say what you touched.** State explicitly that the tree is untouched, or

what changed if implementation was requested separately.

4. "What are the cons?"

Answer as **con → mitigation pairs**, grouped by how much they matter, and say plainly which group each falls in:

• **Blocker.** Must ship in the same PR or the feature is a regression.
• **Verify before merge.** Fine in principle, needs a number on the bench.
• **Acceptable.** The ordinary cost of the approach. Name it and move on.

Every con gets a mitigation or it isn't finished. A con with no mitigation is a blocker by definition.

5. Worked example (issue 198, single-port proxy)

> **What they want.** Jiaocz runs TokenTelemetry behind Pangolin, a reverse > proxy that maps a *domain* to *one* port. They want the API reachable > through the web port so one domain is enough. Same root cause as issue 96 > (SSH tunnel with only 3000 forwarded). > > **What breaks.** TokenTelemetry runs two servers: 3000 serves the page, 8000 > serves the data. > 1. You open `tt.mydomain.com`. The dashboard loads, layout fine. > 2. The page fetches `tt.mydomain.com:8000` for sessions. > 3. Nothing is there. The proxy only published 3000. > 4. Empty shell. Blank charts, zero sessions. > > **Today.** `frontend/src/lib/api.ts` builds `API_BASE` from > `window.location.hostname` plus `NEXT_PUBLIC_API_PORT`. Everything funnels > through `apiFetch`, no SSE, no WebSockets, one binary endpoint. > > **The trap.** `RemoteAuthMiddleware` (`backend/main.py:228`) exempts > loopback. Proxy everything through Next and every request arrives from > 127.0.0.1, so the token gate is bypassed for the whole internet and > `/remote-access` (`main.py:5709`) hands the token to any visitor who asks.

Note what the example does. The failure is walked before a single filename appears, and the security trap is stated consequence-first ("bypassed for the whole internet"), not as a description of middleware registration order.

6. Don't

• Don't open a worktree or edit files. This skill is read-only.
• Don't comment on the issue, close it, or label it unless asked.
• Don't use