bug-capture

# bug-capture Turn a conversation into an issue that still reads correctly after a major refactor. ## Flow ### 1. Listen, then clarify minimally Let the user describe the problem in their own words. Ask at most two short clarifying questions, drawn from: - Expected behavior vs. actual behavior. - Concrete reproduction steps if not already implied. - Frequency: deterministic, intermittent, or one-off. If the description already answers these, skip straight to filing. Over- interviewing is a tax the reporter pays for your uncertainty. ### 2. Explore in parallel While the user is answering, start a background exploration of the relevant area. The goal is **not** to propose a fix. The goal is to absorb the project's own vocabulary — the nouns and verbs the codebase uses for this feature — so the issue reads like it was written by a maintainer. If the repo has a glossary file (common names: GLOSSARY.md, UBIQUITOUS_LANGUAGE.md, docs/domain.md), read it first. ### 3. Check for duplicates before filing Run `gh issue list --search "<key phrase>" --state all --limit 10`. If a live or recently closed issue matches, surface it to the user and ask whether to add a comment instead of opening a new issue. Do not silently skip filing. ### 4. Decide: single issue or breakdown Break down when the report contains two or more independent failure modes that a different contributor could fix in parallel. Keep as one when every symptom traces to a single wrong behavior. For a breakdown, file in dependency order so each child issue can reference a real parent number, and mark honest `Blocked by` links. Avoid inventing dependencies to make the tree look tidier. ### 5. File with `gh issue create` File without asking the user to review the draft. Send back the URLs. #### Single-issue template ``` ## What happened <observed behavior, in domain terms> ## What I expected <expected behavior> ## Reproduction 1. <step> 2. <step> 3. <step> ## Context <anything that narrows where the bug lives, in domain terms — e.g. "only affects the import path, not the export path"> ``` #### Child-issue template ``` ## Parent #<parent-number> ## What is wrong <one behavior, narrow slice> ## What I expected <expected for this slice> ## Reproduction 1. <step> ## Blocked by <#issue or "none — independent"> ## Context <notes that apply only to this slice> ``` ### 6. Rules that apply to every issue body - No file paths, line numbers, function names, or PR numbers. These go stale. Describe behavior, not code. - Use the project's domain nouns, not generic tech terms. "The sync worker drops the patch" beats "`applyPatch()` throws". - Reproduction steps are mandatory. If you cannot derive them, go back to the user once before filing. - Thirty-second read target. Cut anything that does not help a maintainer decide whether to pick it up. ### 7. Keep going After each issue, print the URL and ask whether there is a next one. Do not batch multiple reports into one filing pass — each bug deserves its own scoped issue.