tokentelemetry: Skill for Claude Code

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?").