Turn a Bug Report Into an AI Agent Runbook

A bug report is not automatically a good agent task.

If Claude Code or Codex gets a vague issue like "the settings page is broken," the session may spend more time discovering the shape of the problem than solving it. That is not because the agent is weak. It is because the input was not yet a runbook.

A runbook turns the report into an execution plan with boundaries, verification, and an obvious stop condition.

What A Runbook Needs

A useful bug-fix runbook answers six questions:

1. What is broken?
2. Where does the failure appear?
3. How do we reproduce it?
4. What is in scope?
5. What proves the fix?
6. When should the agent stop and ask for help?

If any of those are missing, the agent has room to guess. Guessing is expensive when the codebase is real and the repo has shared state.

Turn The Bug Report Into Inputs

Start by making the report concrete.

Replace:

• "the onboarding form is weird"

with:

• the file or route where it fails,
• the user action that triggers the bug,
• the expected result,
• the actual result,
• and the command that can verify a fix.

That is the difference between a complaint and a task.

Junction's control surface helps because you can keep the local repo, output stream, approvals, and diff visible while the run works through the bug. That makes it easier to keep the task on target.

A Good Bug Runbook Template

Use a template like this before the session starts:

Goal:
- Fix the failing settings-page test without changing unrelated app behavior.
 
Scope:
- Only edit the settings page and the related test file.
- Do not change billing logic, auth flow, or product copy outside the reported area.
 
Reproduction:
- Run the focused site test for the settings page.
 
Verification:
- Re-run the same focused test after the patch.
- If the change touches shared logic, explain why before editing extra files.
 
Stop condition:
- If the failure appears to be a product decision, stop and summarize the options.

That template is short, but it gives the agent enough to stay bounded.

Add Triage Before Repair

The runbook should start with diagnosis, not code.

Good triage order:

1. Reproduce the issue.
2. Inspect the smallest relevant file set.
3. Decide whether the bug is local, shared, or upstream.
4. Confirm whether the fix belongs in code, config, or test coverage.
5. Patch the narrowest thing that explains the failure.

That sequence keeps the agent from rewriting too much too early.

If the bug report is already well scoped, this is easy. If it is not, the session should spend its first turns narrowing the problem before any edits happen.

Decide What Counts As Done

A runbook is not complete until it tells you how to stop.

Useful stop conditions include:

• the fix requires a broader refactor,
• the failing behavior appears in more than one repo,
• the issue depends on a product decision,
• the bug is actually two bugs,
• or the patch would touch a shared surface you did not intend to change.

That matters because a lot of "bug reports" are really unclear product requests. A good agent runbook should surface that quickly instead of hiding it in the middle of a long debugging session.

Example: From Vague Report To Runnable Task

Imagine someone reports:

The pricing page looks wrong on mobile after the latest change.

That is not enough.

A runnable version would say:

• Reproduce the mobile layout bug on the pricing page.
• Inspect the pricing page component and the related test.
• Keep the change limited to layout and copy.
• Do not change plan prices, billing behavior, or routing.
• Run the focused pricing test and then the site typecheck if the patch is small.

Now the agent has enough context to stay useful.

Use The Runbook With Review, Not Instead Of Review

The runbook is a start, not a replacement for review.

After the agent finishes:

• inspect the diff,
• check the transcript,
• verify the test,
• and confirm that the result still matches the scope.

That is why Turn Local AI Agent Runs Into Pull Requests is the natural next step. A good runbook gets you to a reviewable branch. It does not remove the review.

What Not To Do

Do not hand the agent a screenshot and hope it infers the task.

Do not mix a bug fix with a product rewrite in the same prompt.

Do not omit the stop condition.

Do not let a "small fix" expand into a shared-state change without re-scoping the task.

Where Junction Fits

Junction is useful because the runbook lives next to the run. The agent executes locally, the browser or phone shows the live session, and approvals and diffs stay visible while the bug is being repaired. That gives you a chance to keep the task narrow instead of discovering scope creep after the fact.

If you want to make this a repeatable workflow, start with the Junction setup guide and then compare pricing if you need more than one daemon or more open chats to keep several bug-fix runs moving at once.