File Bug Report

Write an upstream bug report

Create a well-structured bug report for filing against an external project. The report is written to a local markdown file so the user can review before pasting into a GitHub issue.

$ARGUMENTS contains the target repo (owner/repo) and a short summary of the bug.

Workflow

1. Discover upstream contribution norms

Before writing anything, exhaustively search for every piece of guidance the maintainers publish about how they want contributions. Do not skip any of these checks: each one can reveal requirements that, if missed, make the report look careless.

1a. Organization-level community health files

GitHub allows organizations to define default community health files in a .github repository. These files (CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, SUPPORT.md, issue templates, PR templates) are inherited by every repo in the organization that does not provide its own copy. Resolution is per-file: a repo can override one file while inheriting all others.

Check for the org-level .github repo early, since its files set the baseline that subsequent per-repo checks may override:

$ gh api repos/<org>/.github/contents/ --jq '.[].name'

If the repo belongs to an organization (extract <org> from <owner/repo>), fetch and read every community health file found. Common files: CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, SUPPORT.md, FUNDING.yml. Some org repos also contain a readme with links to external contribution guides: follow those links.

If the org has no .github repo or the request returns 404, skip this step. If the repo owner is a user account rather than an organization, skip this step.

When the repo-level checks in subsequent steps find a file that also exists at the org level, the repo-level file takes precedence. When no repo-level file exists, the org-level file is authoritative.

1b. Contribution guidelines

GitHub recognizes contribution guidelines in the repo root, .github/, and docs/, but owners do not always follow GitHub's conventions. File names vary in casing, extension, and placement. Do not assume any single path: check all plausible variations.

Step 1: use the GitHub community endpoint (returns the canonical contributing file regardless of location or casing):

$ gh api repos/<owner/repo>/community/profile --jq '.files.contributing'

If this returns a file, fetch its html_url or url and read it.

Step 2: list the directories where contribution guidelines commonly live. For each directory, list its contents and scan for any file whose name matches contributing (case-insensitive) with any extension:

$ gh api repos/<owner/repo>/contents/ --jq '.[].name'
$ gh api repos/<owner/repo>/contents/.github --jq '.[].name'
$ gh api repos/<owner/repo>/contents/docs --jq '.[].name'
$ gh api repos/<owner/repo>/contents/doc --jq '.[].name'

Look for files matching these patterns (case-insensitive): contributing.md, CONTRIBUTING.md, Contributing.md, CONTRIBUTING.markdown, CONTRIBUTING.rst, CONTRIBUTING.txt, CONTRIBUTING, contributing.adoc, CONTRIBUTING.adoc, or any other variation. Owners may use .rst, .txt, .adoc, .markdown, no extension, or non-standard casing. Fetch and read every match.

Step 3: check the readme for inline contribution guidance or links to external docs:

$ gh api repos/<owner/repo>/readme --jq '.download_url'

Fetch the readme and scan for headings like "Contributing", "How to contribute", "Bug reports", "Filing issues", "Reporting bugs", "Development", or links to external contribution guides (wikis, documentation sites, readthedocs pages). If a link points to an external URL, fetch and read it.

Step 4: check the wiki. Some projects put contribution guidelines in their GitHub wiki:

$ gh api repos/<owner/repo> --jq '.has_wiki'

If the wiki is enabled, note this for the user: the wiki may contain additional contribution norms that cannot be fetched via the API. Suggest the user check https://github.com/<owner/repo>/wiki for pages like "Contributing", "How to file a bug", etc.

1c. Code of conduct

Check for a code of conduct (it sometimes contains issue-filing etiquette):

$ gh api repos/<owner/repo>/contents/CODE_OF_CONDUCT.md --jq '.download_url'
$ gh api repos/<owner/repo>/contents/.github/CODE_OF_CONDUCT.md --jq '.download_url'
$ gh api repos/<owner/repo>/community/code_of_conduct --jq '.body'

1d. Issue templates and forms

List all issue templates. Repos may use classic markdown templates, YAML issue forms, or both:

$ gh api repos/<owner/repo>/contents/.github/ISSUE_TEMPLATE --jq '.[].name'

Fetch every template and form found. Identify which one is the correct match for a bug report by examining filenames and content. Common patterns:

• bug_report.md / bug_report.yml / bug-report.yml: bug reports.
• feature_request.md / feature_request.yml: feature requests (skip).
• security.md / SECURITY.md: security disclosures (use only if the bug is a security issue).
• config.yml: template chooser config that may redirect users to discussions or external links.

If the repo uses YAML issue forms (.yml files with type: input, type: textarea, etc.), the report must fill in each required field using the exact field labels as section headers, preserving the order from the form. Optional fields should be included if relevant evidence exists.

If the repo uses markdown templates (.md files with HTML comments like <!-- description -->), follow the template structure and replace placeholders.

If no templates exist, use the default structure from step 5.

Also check the template chooser config for redirection:

$ gh api repos/<owner/repo>/contents/.github/ISSUE_TEMPLATE/config.yml --jq '.content' | base64 -d

This file may disable blank issues (blank_issues_enabled: false) or add links that redirect users to discussions, forums, or other channels. Respect these preferences.

1e. Security policy

If the bug has security implications, check for a security policy first:

$ gh api repos/<owner/repo>/contents/SECURITY.md --jq '.download_url'
$ gh api repos/<owner/repo>/contents/.github/SECURITY.md --jq '.download_url'

If a security policy exists and the bug is a vulnerability, warn the user that it should be reported through the security channel (often a private advisory or email), not a public issue. Stop and report this to the user.

1f. Discussions preference

Some maintainers require opening a discussion before filing an issue. Check for signals:

$ gh api repos/<owner/repo> --jq '.has_discussions'

If discussions are enabled, search for patterns in the contribution guidelines that say things like "open a discussion first", "please ask in discussions before filing", "use discussions for questions and bug reports". Also check if the template chooser config redirects to discussions.

If the maintainers prefer discussions first, warn the user and suggest opening a discussion instead. Write the report in a tone appropriate for a discussion (same factual content, but framed as "I encountered this, is this a known issue?" rather than a direct bug report).

1g. PR and issue cross-reference conventions

While reading contribution guidelines, note any rules about:

• Whether PRs require a linked issue first ("please open an issue before submitting a PR").
• Whether issues should include attempted fixes or just describe the problem.
• Label conventions the maintainer wants reporters to use.
• Required information the maintainer explicitly asks for (specific version commands to run, config files to include, etc.).

2. Search for existing issues

Check whether the bug is already reported:

$ gh search issues --repo <owner/repo> "<keywords>" --json title,url,state
$ gh issue list --repo <owner/repo> --state all --json title,url,state

Search with multiple keyword variations (error messages, function names, symptoms). Check both open and closed issues: the bug may have been reported and closed as "won't fix", or fixed in a version the user hasn't upgraded to.

If a matching open issue exists, report it to the user and stop. If a matching closed issue exists, mention it in the report with a link and explain why this is a new occurrence (different version, different context, regression).

A matching issue closed for lack of a reproducer is not a dead end: cite it, because that closure is part of the record, and supply what it lacked.

3. Gather evidence

Collect the actual error output, environment details, and reproduction steps from the current conversation context, CI logs, or local files. Always include:

• Exact error messages and tracebacks (not paraphrased).
• Version numbers of the failing tool. Run any version commands the contribution guidelines specify.
• OS and architecture.
• CI run URL if applicable.
• Any additional environment details the issue template or contribution guidelines explicitly request.

Link to public context

Maintainers can diagnose faster when they can see the original context themselves. Whenever the triggering context is publicly accessible, include deep links in the report:

• CI run logs: link to the specific GitHub Actions run (or step anchor) that shows the failure, not just the repo. Use gh run view <run-id> --json url --jq '.url' to get the URL.
• Source code: link to the exact file and line(s) in the user's public repo that trigger the bug, using GitHub's permalink format (https://github.com/<owner/repo>/blob/<sha>/path/to/file.py#L42-L55). Use a commit SHA, not a branch name, so the link stays stable.
• Configuration files: if the bug depends on a specific config (workflow YAML, pyproject.toml section, tool config), link to it.
• PR or commit diffs: if the bug surfaced after a specific change, link to the PR's file diff (e.g., https://github.com/owner/repo/pull/123/changes#diff-<hash>) or the commit, not just the PR landing page. The reader should see the relevant change immediately on click.

Ask yourself: "Can the maintainer click a link and immediately see what I'm describing?" If yes, include the link. If the context is private, quote the relevant snippet inline instead.

Observations, not conclusions

The maintainer of the code is the authority on it. Hand over observations they can verify in one click, and leave the diagnosis to them:

• Link every factual claim to the exact line that proves it. A claim drawn from a CI log links the log line (see § GitHub Actions log anchors below); a claim that exists only in an uploaded artifact links the artifact, since no log line proves it.
• Check a claim about the upstream tool against its source or manual before writing it. Memory is not a source. Where a code comment in the tool says it better, quote the comment verbatim and link it.
• Date a behavior by the commit that added it, not by the release note that announced it. Release notes list what is worth reading about now, not what shipped now: git tag --contains {sha} | sort -V | head -1 names the first release that carried the commit.
• Report what varied, where, and the link to it, then stop. Leave the diagnosis, its implications for CI or users, and the next step to the maintainer, who reaches them faster from the facts than from a summary of them.
• Give every failing reproducer a passing control beside it. Without a near-identical case that passes, red cannot be told apart from a broken harness, a missing dependency or a mistake in the reproducer. Assert the control too, and have the job report the test as void when the control breaks.
• Freeze the reproducer's vocabulary once the prose quotes it. Renaming a log line, an artifact or a path that the report quotes forces a rerun, then a repoint of every link and quoted phrase.
• Re-read the draft before handing anyone steps to reproduce. Give only the steps the draft records as reproducible, and flag a symptom seen only once as a one-off.

GitHub Actions log anchors

A …/actions/runs/{run}/job/{job}#step:{N}:{line} link follows non-obvious numbering, verified against live runs:

• Fetch the raw log with gh api repos/{owner}/{repo}/actions/jobs/{id}/logs --allow-escape-sequences. Without the flag, gh refuses the escape sequences and writes an empty file. The job's numeric ID is id in gh api repos/{owner}/{repo}/actions/runs/{run}/jobs, and databaseId in gh run view {run} --json jobs, which has no id field: reading .id there returns null.
• The step number counts "Set up job" as 1, so a workflow's sixth step is step:7.
• Read that number from the API, never by counting log sections. The raw log omits a skipped step while the fragment still counts it, so one if:-guarded step shifts every anchor below it by one, and only on the runs where it was skipped. gh api repos/{owner}/{repo}/actions/jobs/{id} returns steps[].number and steps[].conclusion: line the non-skipped steps up against the log's ##[group]Run markers in order, then take the number off the step. Its name is also the cheapest check that an anchor landed where intended.
• The line number starts at the step's ##[group]Run … marker, which is line 1, and includes the echoed script plus the shell:/env: preamble before any output.
• Strip the leading timestamp (^\S+Z ) from each raw line before counting or matching.
• Anchors rot on every rerun. Any change in a job's output shifts every line below it, and a tool printing one extra banner line moves anchors nobody touched. After a rerun, repoint every anchor programmatically and re-resolve each one against the new logs to confirm it still lands on the intended line; never trust the arithmetic.

4. Select the right template

Based on step 1d, pick the correct template:

• Bug report template/form found: use it. Fill in every required field. Preserve the exact field names, order, and structure.
• Multiple templates exist but none is a clear bug report match: report this to the user and ask which template to use.
• No templates found: use the default structure in step 5.
• Template chooser disables blank issues and no bug template exists: warn the user that the repo may not accept bug reports through issues.