issue-brief
Skill388 starsChanged 4 months agoMITView on GitHub
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.
In this repository9 other files it gives its agents.
- AGENTS.mdAGENTS.md
- frontend/AGENTS.mdAGENTS.md
- website/AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- frontend/CLAUDE.mdCLAUDE.md
- website/CLAUDE.mdCLAUDE.md
- llms.txtllms.txt
- bug-auditSkill
- change-briefSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 4 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 82
Blocker: Must ship in the same PR or the feature is a regression.
- Distinctive: line 86
Every con gets a mitigation or it isn't finished.
- Distinctive: line 118
Don't open a worktree or edit files.
- Distinctive: line 119
Don't comment on the issue, close it, or label it unless asked.
- Very specific: line 120
Don't use this for pull requests.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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,commentsDiscussions 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_DIRandtest_pi_scan.pyalready 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
- 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.
- 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.
- How it works today, only the part that bears on the issue, with
file.py:lineanchors so the claim can be checked. - What implementing it would take: the shape of the change and which layer it belongs in, not a full diff.
- Traps and interactions. Security regressions, open PRs on the same files, closed issues with the same root cause, what has to land first.
- 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:lineand 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.
- You open
tt.mydomain.com. The dashboard loads, layout fine.- The page fetches
tt.mydomain.com:8000for sessions.- Nothing is there. The proxy only published 3000.
- Empty shell. Blank charts, zero sessions.
Today.
frontend/src/lib/api.tsbuildsAPI_BASEfromwindow.location.hostnameplusNEXT_PUBLIC_API_PORT. Everything funnels throughapiFetch, 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 this for pull requests.
/reviewcovers those.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

