issue-brief

# 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: ```bash 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: ```bash 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 la...