Good Issue

good-issue

Philosophy

The best way to support OSS is to write good issues. A shining issue does the maintainer's triage work for them: it is actionable in one read, has a verified minimal reproduction, and ideally points at the root cause. Issue creators who do this well become de-facto co-contributors.

Your job as the agent: don't just transcribe the user's complaint — investigate it. Reproduce the bug yourself, minimize it, and dig into the dependency's source before writing a word of the issue.

Workflow

1. Understand the problem

• Get the exact failing behavior from the user: what they did, what happened, what they expected.
• Identify the target project and collect versions: the library, the runtime (node/python/etc.), OS, and package manager. Read the user's lockfile to get exact resolved versions — never trust semver ranges.

2. Check for duplicates (mandatory)

• Search the project's existing issues (open AND closed) for the error message, symptom keywords, and related function names.
• If a duplicate exists: don't file. Instead, offer to add a 👍 + a comment with the user's repro/environment if it adds new signal.
• Also check the project's CHANGELOG/releases — the bug may already be fixed in a newer version. Try upgrading first.

3. Build a minimal reproduction (the core of this skill)

• Start from the user's failing code and cut aggressively: remove every dependency, config option, and line that isn't required to trigger the bug.
• Target: a single file or a tiny repo scaffold (npm init-level) that fails with one command.
• Actually run it. A repro you haven't executed is a hypothesis, not a repro. Confirm it fails for the stated reason, and confirm it passes when the suspected trigger is removed (falsifiability check).
• If the bug is version-specific, bisect: find the last good and first bad version and say so in the issue.
• See references/repro-checklist.md for the full quality bar.

4. Investigate root cause (best effort)

• Read the dependency's source in node_modules (or clone it). Follow the stack trace to the responsible function.
• If you can identify the faulty line(s), include a "Likely cause" section with file paths and line numbers, and — if obvious — a suggested fix or PR offer.
• Don't guess. If you're not sure, say "I traced it as far as X" rather than asserting a wrong cause.

5. Write the issue

• Follow the project's issue template if one exists (.github/ISSUE_TEMPLATE/). Fill every field; never leave template placeholders in.
• Otherwise use references/bug-report.md or references/feature-request.md.
• Title format: symptom + trigger, searchable. E.g. `parseConfig` throws TypeError when env value contains `=` (v3.2.1)
• One issue per issue. If you found two bugs, write two issues.

6. Review with the user, then file

• Show the user the final draft and the repro before submitting anything.
• Offer to file via gh issue create and, if the repro warrants it, push the repro to a public repo (StackBlitz/CodeSandbox link or a minimal GitHub repo) with the user's approval. Never publish anything containing user secrets, private code, or internal URLs — scrub the repro.

Quality bar (all must be true before filing)

• Repro executed and confirmed failing by the agent, not just the user
• Repro is minimal — nothing can be removed without the bug disappearing
• Exact versions listed (library, runtime, OS)
• Expected vs. actual behavior stated explicitly
• Duplicate search done (link related issues if any)
• Title is searchable and specific
• No secrets or private code in the issue or repro