upstream-bug-report

Files (1)

• SKILL.md

SKILL.md (first lines)

# upstream-bug-report

## Overview

A third-party tool fails, the cause turns out to be in its code, and the next
step is an issue on someone else's public repository. That write crosses a
boundary: it is public, it cannot be unsent, and a report whose reproduction
only works on your patched machine wastes the maintainer's time. Most bad
upstream reports fail on one of three things — they blame upstream for a local
problem, they quote output from a tree that is not upstream, or they duplicate
an existing report.

This skill orders the work so each of those is closed before the body is
drafted, and the post happens only after the user has seen the exact title and
body.

**Core principle:** every command in the issue body is a transcription of a run
on pristine upstream that produced the quoted output.

## When to Use

- An installed plugin, server, or library misbehaves and the defect is in its
  code, not in the local setup.
- The user asks to report a bug upstream or to open an upstream issue.
- A contributor opened a PR for an issue you filed and the user asks how well
  it covers it (Step 8).

## The Iron Law

- **Public writes are approval-gated, one action at a time.** Issue, PR, and
  review comment each need their own explicit approval of the exact text.
- **No internal identifiers in the body.** English, synthetic ids and labels,
  `<checkout>` placeholders instead of home paths, no account names.
- **Always `--body-file`.** Never inline a multi-line body in the command.

## Process

### Step 1: Diagnose locally before blaming upstream

- **Read the error class first, as a clue, not a verdict.** A 401 says
  authentication failed: the credential may be missing from the process, or
  present but invalid or expired. A 400/422 points at the request, but the
  vendor may use it for other rejections too. Read the response body, and
  check the credential's presence (without printing it) and its validity
  before naming a cause. A 401 → 422 transition after adding a key suggests
  auth now works and the next problem is in the payload — confirm it from the
  422's response body.
- **A long-running server process keeps the env and code it started with.** A
  tool served by an already-running MCP server or daemon stays stale until
  that process restarts. Test a fix in a **fresh process** — import the module
  with the plugin's own interpreter (its `.venv/bin/python`), loading the
  credential from your env file inside the same command without printing it.
- **Prove the fix in memory before editing files.** Monkeypatch the call (for
  example wrap the request function to add the missing field) and run one
  positive case and one negative or abstain case. Only then patch the file and
  re-run without the monkeypatch. Tell the user the edit is local-only:
  uncommitted, and overwritten by the next plugin update.
- **Confirm the vendor contract from official docs** (the API reference page
  that says the field is required) and keep the URL for the report.

Done when: the defect is attributed to upstream code with a fresh-process
positive and negative run, and the vendor contract is cited by URL — or it is
attributed to local setup and the skill stops.

### Step 2: Reproduce on pristine upstream

Do not reproduce on the locally patched tree.

- **Single module:** extract the upstream file at the installed commit into a
  scratch directory outside any repository —
  `git -C <plugin> show <sha>:<path> > <scratch>/module.py` (plus its
  `__init__.py`) — and run the exact reproduce command you will put in the
  body from there.
- **Whole package** (when the local install carries patches on top of
  upstream): check out the latest upstream head instead. A local `origin` may
  be a fork and the default branch may not be `main`, so resolve both from
  the canonical repository first —
  `gh repo view <r> --json url,defaultBranchRef --jq '.url, .defaultBranchRef.name'`
  — then fetch by URL:
  `git -C <repo> fetch <upstream-url> <default-branch> && git -C <repo> worktree add --detach <scratch>/<name>-upstream FETCH_HEAD`.
  Point the import path at it, run the repro, then `git worktree remove` it.
  Reproducing on the upstream default branch rather than the installed commit
  also answers "is it already fixed"; cite that SHA in the body.
- **Self-contained:** a throwaway config/home directory, synthetic ids and
  labels, `<checkout>` placeholders — so the repro carries no account names or
  local state.

Done when: the reproduce command, run on pristine upstream at a named SHA,
printed the same error you will quote.

### Step 3: Dedup

```bash
gh issue list --repo <r> --state all --search "<phrase>"
gh search issues --repo <r> "<phrase>"
gh search prs --repo <r> "<phrase>"
```

For a repo of a few hundred issues, or one whose reports are multilingual
(CJK titles are common on AI-tool repos), pull the whole corpus once and
filter locally instead — it covers every language and both states in one
pass:

```bash
gh issue list --repo <r> --state all --limit 1000 \
  --json number,title,state,createdAt,url,body > "$TMPDIR/<r>-issues.json"
# then regex title+body in python, including CJK/Korean synonyms
# (e.g. shortcut|hotkey|快捷键|단축키, sidebar|collapse|折叠|收起|접기)
```

Check the count against `--limit`. Give `gh search issues` a positive
control: if it returns `[]` for a phrase a known issue contains, discard its
empty results and rely on the local filter.

Run several phrasings: the symptom, the function name, and a mechanism word
(for example `tombstone`, `resurrect`). Report the result with its scan scope
(the phrasings used), plus the closest related-but-different reports and why
they differ — those go into the body too. praxis's
`block-gh-issue-create-without-dup-search` hook blocks `gh issue create`

From devseunggwan/praxis, MIT.

More from devseunggwan/praxis