Turn a GitHub Issue Into an AI-Ready Bug Packet

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.

A real issue with three link behaviors

MonkeyCode issue #824 reports that clicking a Markdown link beginning with /workspace/... returned the application home page instead of opening the file. The corresponding PR #859 makes the interaction more specific:

• a normal click should open the task file preview;
• opening a new tab should preserve a file-manager deep link;
• copying the link should preserve that deep link too.

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 packet

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?

Fail vague packets before the agent runs

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.

How I would hand this to an agent

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.