Dashboard

How to Prompt AI to Write a GitHub Issue That Gets Fixed

A prompt that turns a rambling bug report or feature idea into a GitHub issue someone can act on, with a before and after and a pre-posting check.

Steve Jefferson
Steve Jefferson
Developer Advocate
28 October 20261 min read

To get a usable GitHub issue from AI, give the model your raw notes and tell it two things: the structure to follow, and to ask you questions instead of inventing details it does not have. That second instruction is the one that matters. Without it, a model fills gaps with plausible steps and made-up version numbers, and you end up with a confident issue nobody can reproduce.

Here is the prompt, then why each part is there.

The prompt

You are helping me write a GitHub issue. Use only the facts in my notes.
If something needed for the issue is missing, list it under "Questions for
me" and do not guess.

Write the issue with these sections:
- Title: under 70 characters, names the symptom, no "bug" or "issue" filler
- Summary: two sentences, what is wrong and who it affects
- Steps to reproduce: numbered, one action per step
- Expected result
- Actual result: include any error text exactly as I gave it
- Environment: only what I listed
- Notes: anything else relevant, such as how often it happens

If this is a feature request, replace the reproduce steps with "Problem
to solve" and "Proposed behavior".

My notes:
[paste notes, error text, screenshots described in words]

Why each piece is there

"Use only the facts in my notes." This blocks invention. Models like to complete a pattern, and a bug report has a strong pattern, so they will add "Chrome 120 on macOS" if you do not stop them.

The "Questions for me" section. Missing facts become a to-do list. You answer them, paste them back, and the second draft is far better than the first.

A title rule. Titles are what maintainers scan. "Login fails" is vague. "Login returns 500 when email contains a plus sign" tells someone where to look.

Numbered steps, one action each. A step like "Go to settings and change your email and save" is three steps and hides which one fails.

Exact error text. Tell the model to keep error messages verbatim. A paraphrased error cannot be searched for.

A before and after

Raw notes:

checkout is broken again, customers say they pay and nothing happens, it was fine last week i think, happened to like 3 people, one used safari

A first-pass prompt with the template above should not produce a finished issue from that. It should come back with something like:

Questions for me

  • What does the customer see after paying: a blank page, an error, or the same checkout page?

  • Do you have the order or payment IDs for the three cases?

  • What changed last week: a deploy, a new payment setting, or a dependency update?

  • Do you have any error message from the browser or the server logs?

  • Did the two other customers use Safari too?

That list is the value. Reply with what you know:

Same checkout page, no error. Payment goes through in the payment dashboard but no order appears. Deploy last Thursday updated the payments library. Two other customers used Chrome. No server errors found.

Now the model can write:

Title: Paid checkouts create no order after payments library update

Summary: Since the deploy last Thursday, at least three customers completed payment but no order record was created. The checkout page reloads with no error.

Steps to reproduce: Not yet reproduced. Needs a test payment, see Notes.

Expected: An order is created and the customer sees a confirmation.

Actual: The payment is captured in the payment dashboard. No order exists. The page returns to checkout without an error.

Notes: Affected customers used Safari and Chrome. The payments library was updated in last Thursday's deploy.

Notice that it wrote "Not yet reproduced" instead of making up steps. That honesty is what the prompt buys you. If you want a deeper look at turning a vague report into something an agent can fix, the guide to writing a bug report for an AI coding agent goes further, and making an AI coding agent reproduce a bug first is the natural next step.

Feature requests need a different shape

A feature issue should start from the problem, not the solution. Change the prompt to ask for "Problem to solve" and "Proposed behavior", and add a line: "List two alternatives I should consider." Models are good at that last one, and it keeps the issue from locking in the first idea. If you want the acceptance side spelled out, see writing acceptance criteria for an AI coding agent, and for a more user-centered framing use the user story prompt.

Let the repository do some of the work

If you maintain the repository, you do not have to paste a prompt every time. GitHub supports issue templates. Per its documentation, issue forms are YAML files stored at .github/ISSUE_TEMPLATE/FORM-NAME.yml, with fields such as input, textarea, dropdown, and checkboxes, and each field can be marked required. A bug form with required "steps" and "expected result" fields means every reporter answers the questions your prompt was asking. See GitHub's issue template documentation for the schema.

You can even ask AI to draft the form file. Give it your list of must-have fields and ask for valid YAML, then test the form on a throwaway issue before relying on it.

Check before you post

Run through five points:

  1. Could a stranger reproduce it from the steps alone?

  2. Is every version, device, and setting something you actually told the model?

  3. Is the error text pasted exactly?

  4. Did you remove secrets? Tokens, API keys, customer emails, and internal URLs sometimes ride along in logs and screenshots.

  5. Is it one problem? If the issue contains two bugs, split it.

When AI is the wrong tool

If you do not yet understand the bug, an issue will not help. Reproduce it first. Models are good at structuring facts, and poor at discovering them. For the wider craft of getting reliable output, the overview of prompt engineering shows the habits behind prompts like this one.

FAQ

Can AI write a GitHub issue?

Yes, from your notes. It structures the facts well. It should be told not to guess missing details, or it will invent them.

What should a good GitHub issue include?

A specific title, a short summary, numbered steps to reproduce, expected and actual results, the exact error text, and the environment.

What is a GitHub issue template?

A file in your repository that pre-fills new issues with a structure. Issue forms add web form fields that can be marked required.

Should I let an AI agent open issues automatically?

Be careful. Automatic issues can flood a tracker with duplicates. Have the agent draft them and let a person approve the ones worth filing.

How long should a GitHub issue be?

As long as it takes to reproduce and understand the problem, and no longer. Short and complete beats long and vague.

How did this land?

About the author

Steve Jefferson
Steve Jefferson

Developer Advocate

Steve builds something with Swarmz every week and writes up what worked, what broke, and what he'd do differently. Tutorials and hands-on guides are his lane.

Share

Get the next post in your inbox

One email a month. Product updates, engineering posts, and the best of Built with Swarmz.

I agree to receive emails about AI building tips and Swarmz product news. Unsubscribe any time.