{"slug": "turn-a-github-issue-into-an-ai-ready-bug-packet", "title": "Turn a GitHub Issue Into an AI-Ready Bug Packet", "summary": "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.", "body_md": "I like short bug reports right up to the moment I ask a coding agent to fix one.\n\n“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.\n\nA better input is a **bug packet**: one small, machine-checkable record that connects reproduction, evidence, scope, and acceptance.\n\n[MonkeyCode](https://github.com/chaitin/MonkeyCode) issue [#824](https://github.com/chaitin/MonkeyCode/issues/824) reports that clicking a Markdown link beginning with `/workspace/...`\n\nreturned the application home page instead of opening the file.\n\nThe corresponding [PR #859](https://github.com/chaitin/MonkeyCode/pull/859) makes the interaction more specific:\n\nThe 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.\n\nThat distinction is small and useful. Agents need to know what is observed, what another author reported, and what remains unknown.\n\nThe companion `bug-packet.json`\n\npins the reviewed commit and stores the issue in nine fields:\n\n```\n{\n  \"schema_version\": 1,\n  \"title\": \"Markdown workspace link opens the app home page\",\n  \"source_issue\": \"https://github.com/chaitin/MonkeyCode/issues/824\",\n  \"candidate_fix\": \"https://github.com/chaitin/MonkeyCode/pull/859\",\n  \"environment\": {\n    \"revision\": \"c58bcd4dd4b7031f469a1271f276d22550b8f523\",\n    \"surface\": \"web task Markdown preview\"\n  },\n  \"reproduction\": [\n    \"Open a task whose Markdown contains a /workspace/... link\",\n    \"Click the link normally\",\n    \"Observe the destination\"\n  ],\n  \"expected\": \"The task file preview opens for the linked workspace file.\",\n  \"observed\": \"The application home page opens.\",\n  \"acceptance\": [\n    \"Normal click opens the task file preview\",\n    \"Open-in-new-tab preserves a file-manager deep link\",\n    \"Copy-link preserves a file-manager deep link\"\n  ],\n  \"evidence\": [\"Issue 824 describes the failing path\"],\n  \"unknowns\": [\"Browser and deployment details were not supplied\"]\n}\n```\n\nWhy these fields?\n\n| Field | Mistake it prevents |\n|---|---|\n| Revision | Editing code that no longer matches the report |\n| Reproduction | Fixing a guessed path |\n| Expected + observed | Treating “broken” as a specification |\n| Acceptance | Solving normal click while breaking modifier-click behavior |\n| Evidence | Presenting somebody else's checks as freshly verified |\n| Unknowns | Quietly filling gaps with plausible fiction |\n\nThe included Node.js validator requires ordered reproduction, at least one acceptance assertion, a source URL, and explicit unknowns:\n\n```\nnode validate-bug-packet.mjs bug-packet.json\nnode test-bug-packet.mjs\n```\n\nExpected output:\n\n```\nPASS bug packet\nPASS complete packet; rejected vague packet\n```\n\nThe 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.\n\nMy task prompt would be short because the packet carries the facts:\n\n```\nRead bug-packet.json. Reproduce only on the pinned revision.\nWrite a failing test for all acceptance behaviors before changing routing.\nDo not broaden URL handling beyond the stated /workspace path.\nReturn changed files, test output, and any packet unknowns that remain.\n```\n\nThe human still owns scope. The agent gets enough structured context to investigate without pretending the issue already proves the cause.\n\nYou 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.\n\nThe 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.\n\nDisclosure: I contribute to the MonkeyCode project. The case above is based on the linked public issue, pull request, and repository at commit\n\n`c58bcd4`\n\n; the standalone packet validator was tested locally.", "url": "https://wpnews.pro/news/turn-a-github-issue-into-an-ai-ready-bug-packet", "canonical_source": "https://dev.to/rivera123/turn-a-github-issue-into-an-ai-ready-bug-packet-22o8", "published_at": "2026-07-14 06:15:36+00:00", "updated_at": "2026-07-14 06:31:56.498696+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "machine-learning"], "entities": ["MonkeyCode", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/turn-a-github-issue-into-an-ai-ready-bug-packet", "markdown": "https://wpnews.pro/news/turn-a-github-issue-into-an-ai-ready-bug-packet.md", "text": "https://wpnews.pro/news/turn-a-github-issue-into-an-ai-ready-bug-packet.txt", "jsonld": "https://wpnews.pro/news/turn-a-github-issue-into-an-ai-ready-bug-packet.jsonld"}}