Turn a GitHub Issue Into an AI-Ready Bug Packet

A developer created a structured 'bug packet' format to convert GitHub issues into AI-ready inputs for coding agents. The format, demonstrated on MonkeyCode issue #824, includes fields for reproduction steps, expected vs. observed behavior, acceptance criteria, and explicit unknowns. The developer argues that this structured approach reduces ambiguity for AI agents and improves human issue tracking.

I like short bug reports right up to the moment I ask a coding agent to fix one. “Markdown links are broken” leaves the agent to invent the environment, the click behavior, the expected route, and the definition of done. That is not autonomy. It is a very fast ambiguity generator. A better input is a bug packet : one small, machine-checkable record that connects reproduction, evidence, scope, and acceptance. MonkeyCode https://github.com/chaitin/MonkeyCode issue 824 https://github.com/chaitin/MonkeyCode/issues/824 reports that clicking a Markdown link beginning with /workspace/... returned the application home page instead of opening the file. The corresponding PR 859 https://github.com/chaitin/MonkeyCode/pull/859 makes the interaction more specific: The PR reports lint, an online build, and manual Markdown-link checks. I did not rerun those project-level checks for this article, so the packet records them as source evidence rather than my test results. That distinction is small and useful. Agents need to know what is observed, what another author reported, and what remains unknown. The companion bug-packet.json pins the reviewed commit and stores the issue in nine fields: { "schema version": 1, "title": "Markdown workspace link opens the app home page", "source issue": "https://github.com/chaitin/MonkeyCode/issues/824", "candidate fix": "https://github.com/chaitin/MonkeyCode/pull/859", "environment": { "revision": "c58bcd4dd4b7031f469a1271f276d22550b8f523", "surface": "web task Markdown preview" }, "reproduction": "Open a task whose Markdown contains a /workspace/... link", "Click the link normally", "Observe the destination" , "expected": "The task file preview opens for the linked workspace file.", "observed": "The application home page opens.", "acceptance": "Normal click opens the task file preview", "Open-in-new-tab preserves a file-manager deep link", "Copy-link preserves a file-manager deep link" , "evidence": "Issue 824 describes the failing path" , "unknowns": "Browser and deployment details were not supplied" } Why these fields? | Field | Mistake it prevents | |---|---| | Revision | Editing code that no longer matches the report | | Reproduction | Fixing a guessed path | | Expected + observed | Treating “broken” as a specification | | Acceptance | Solving normal click while breaking modifier-click behavior | | Evidence | Presenting somebody else's checks as freshly verified | | Unknowns | Quietly filling gaps with plausible fiction | The included Node.js validator requires ordered reproduction, at least one acceptance assertion, a source URL, and explicit unknowns: node validate-bug-packet.mjs bug-packet.json node test-bug-packet.mjs Expected output: PASS bug packet PASS complete packet; rejected vague packet The test also passes in a deliberately vague record and confirms that it is rejected. That is the part I want in CI. A schema that only demonstrates its happy path becomes another nice-looking document nobody can trust. My task prompt would be short because the packet carries the facts: Read bug-packet.json. Reproduce only on the pinned revision. Write a failing test for all acceptance behaviors before changing routing. Do not broaden URL handling beyond the stated /workspace path. Return changed files, test output, and any packet unknowns that remain. The human still owns scope. The agent gets enough structured context to investigate without pretending the issue already proves the cause. You can extend the format with screenshots, fixture paths, browser versions, accessibility expectations, or rollback conditions. Keep those as evidence-bearing fields, not a dump of every comment in the issue. The surprising lesson is that an AI-ready issue is also a better human issue. It separates facts from guesses, makes secondary interactions visible, and gives reviewers an actual finish line. Disclosure: I contribute to the MonkeyCode project. The case above is based on the linked public issue, pull request, and repository at commit c58bcd4 ; the standalone packet validator was tested locally.