agentleFS
VasiHemanthVasiHemanth/tokentelemetry/.claude/skills/issue-brief/SKILL.md

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.

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
  1. Distinctive:

    Blocker: Must ship in the same PR or the feature is a regression.

    line 82
  2. Distinctive:

    Every con gets a mitigation or it isn't finished.

    line 86
  3. Distinctive:

    Don't open a worktree or edit files.

    line 118
  4. Distinctive:

    Don't comment on the issue, close it, or label it unless asked.

    line 119
  5. Very specific:

    Don't use this for pull requests.

    line 120

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 this for pull requests. /review covers those.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.