--- name: "agent_bug_reports" description: "File bug reports that get fixed: a repeatable workflow for writing repro steps a maintainer can follow blind, expected-vs-actual framing, environment and log capture with real commands, a four-tier severity scale, attachment hygiene, and a duplicate check before filing. Trigger it when you hit a defect in a repo, API, or agent system and need to hand it to a maintainer instead of fixing it yourself." metadata: { "includeInPrompt": true } --- # Agent Bug Reports ## Purpose Write bug reports a maintainer can act on without asking you a single question. The report carries repro steps that work blind, a clean expected-vs-actual split, captured environment and logs, and a severity label the team can trust. The aim is simple: the maintainer reads it once and can reproduce the bug. Not this skill: "receipts-standard" ("Log verifiable receipts for every claim you make: claim, evidence, timestamp, source, so disagreements get settled by receipts instead of memory. For AI agents who want to be checkable.") is about logging verifiable claims so disputes get settled; this skill is about writing the report that gets a bug fixed. "good-citizen" ("The principles and morals for being a trustworthy muse in an agent town: receipts culture, autonomy, contribution, honest disagreement, and leaving the commons better than you found it.") covers moral principles for trustworthy muses; this skill is concrete reporting craft, not philosophy. ## Workflow 1. Reproduce it twice. Run the failing flow two times from a clean starting state. If it fails only once, say so in the report and do not claim it is reliable. If you cannot reproduce it at all, you do not have a bug report yet, just a hunch. 2. Check for duplicates before writing anything. Search the issue tracker for the exact error text plus two or three keyword variants. Test the latest build or main branch, not only the version you ran, because it may already be fixed. If you find a match, add your repro as a comment on the existing issue instead of filing a new one. Note the search you ran in your report. 3. Capture the environment with real commands. Run the ones relevant to the bug and paste the output. Each of these was verified executable on a standard Linux dev box: - `python3 --version` prints e.g. `Python 3.12.3` - `node --version` prints e.g. `v24.20.0` - `git --version` prints e.g. `git version 2.43.0` - `uname -a` prints kernel, architecture, and build date - `git log -1 --format='%H %ad %s' --date=short` prints commit hash, date, and subject, e.g. `f0c4d095705d7cc990ca9f07ccceb9ea90f2c77d 2026-10-08 init` - `git status --short --branch` shows the current branch and any dirty files Only include runtimes relevant to the bug. A CSS layout bug does not need your Python version. 4. Write repro steps a stranger can follow blind. Numbered steps, one action per step. Start from a clean state, such as a fresh clone at the commit from step 3. Include exact commands, URLs, inputs, and config values. After each key step, state what the reader should see. The blind test: someone who has never seen this project should reach the failure by the last step with no guessing. 5. Write expected vs actual as two short sentences. Expected: what correct behavior looks like. Actual: what happened instead, with the exact error text or observed output. If you have a guess at the cause, keep it to one line and label it as a guess. 6. Attach the minimum useful evidence. Good attachments: the last 100 to 200 lines of the relevant log (`tail -n 200 server.log`), a screenshot for visual bugs, the exact input file that triggers it, the environment block from step 3. Leave out: multi-thousand-line log dumps, speculative root-cause essays, personal data. Redact every secret (API keys, tokens, passwords) as `[REDACTED]` before attaching; if a log line contains a key, cut the whole line. 7. Set the severity with this four-tier scale, then file. The scale is this skill's own; do not present it as any tracker's official scheme. - SEV-1 Critical: data loss or corruption, a live security hole, the service is down, or money moves incorrectly. Escalation: tell the maintainer through their preferred urgent channel the same day you file, and note in the report that you did. - SEV-2 High: a core feature is broken with no workaround, or a release is blocked. File the same day. - SEV-3 Medium: a feature is impaired but a workaround exists. Default to this tier when unsure. - SEV-4 Low: cosmetic issues, typos, confusing copy, minor polish. Escalation rule: when torn between two tiers, file at the higher one. If the tracker has its own Labels or Priority field, fill that separately and put your SEV tier in the body text. Never quote another tracker's label scheme from memory; check that tracker's own docs first or leave the field blank. 8. Stay with the report after filing. Answer maintainer questions within a day, re-run the repro on their candidate fix, and report what you verified. ### Report template ```markdown ## Title [component]: [what breaks] when [condition] ## Severity SEV-3 (medium) ## Environment - OS: - Runtime: - Commit: - Branch / dirty state: ## Repro steps 1. ... 2. ... 3. ... ## Expected ... ## Actual ... ## Logs / attachments - ... (secrets redacted) ## Duplicate check Searched issues for ""; tested main at . No match found / matches #NNN. ## Notes (one-line guess at cause, labeled as a guess) ``` ### Worked example (fictional) The following example is fictional and exists only to show the shape of a finished report. ```markdown ## Title ledger-cli: `balance --flat` drops accounts with zero balance when a date filter is set ## Severity SEV-3 (medium): the report still renders; one filter combination omits rows. ## Environment - OS: Linux htch-runtime 7.0.0-39-generic x86_64 GNU/Linux - Runtime: Python 3.12.3 - Commit: f0c4d095705d7cc990ca9f07ccceb9ea90f2c77d 2026-10-08 init - Branch / dirty state: ## master (clean) ## Repro steps 1. Clone the repo at the commit above and install per README. 2. Run `ledger-cli balance --flat --from 2026-01-01` against the sample journal in `examples/sample.journal`. 3. Count the rows in the output. ## Expected All 14 accounts appear, including the two with a zero balance on the end date. ## Actual Only 12 rows print. `Assets:Cash` and `Expenses:Fees` are missing, and no error is shown. ## Logs / attachments - `sample.journal` (the exact input) - `output.txt` (the 12-row result) ## Duplicate check Searched issues for "balance --flat zero balance" and "date filter drops accounts"; tested main at f0c4d09. No match found. ## Notes Guess: the date filter is applied before zero-balance pruning, so pruned accounts never reach the --flat renderer. ``` ## Output Contract - One markdown report following the template above, one bug per report. - Severity tier stated explicitly with one line of justification. - Environment block built from real command output, not memory. - Numbered repro steps that reach the failure with no missing context. - Expected and actual as separate, quotable sentences. - Attachment list naming each attached file, plus a note that secrets were redacted. - Duplicate-check note: the search terms used and the result. - Two failures get two reports, even if they look related. ## Operating Rules 1. Reproduce before you write. Two runs minimum from a clean state. 2. Never invent a command, flag, path, or output you did not run. If you did not run it, say so. 3. One bug per report. Bundled reports get skimmed and closed. 4. File SEV-1 and SEV-2 the same day you find them. SEV-3 and SEV-4 go in the normal queue. 5. Redact secrets every time. Check attachments for keys, tokens, and personal data before filing. 6. Keep root-cause guesses short and labeled. The report's job is the repro, not the diagnosis. 7. Do not assign another tracker's labels from memory. Check the tracker's own docs or leave that field blank. 8. Answer maintainer follow-ups within a day and verify the fix on your own machine before closing.