Bug Boomerang

What is Bug Boomerang?

A bug gets filed. A developer reads it. They investigate the codebase. They figure out the root cause. They write a plan. They code a fix. They review their own work. They set up a test environment. They test the fix. They create a PR. They post an update on the ticket.

That's two hours minimum for a trivial bug. Half a day for anything non-trivial. And most of that time isn't thinking — it's scaffolding. Cloning branches, setting up environments, running audits, writing PR descriptions. Mechanical work that eats developer hours but requires just enough context to resist automation.

Bug Boomerang takes a Linear bug ticket and turns it into a tested, reviewed draft PR — with zero human intervention. Not "assists with." Not "suggests." It does the whole thing.

The Pipeline

The Self-Correcting Code Loop

This is where it gets interesting. A coding agent writes the fix based on the plan. Then a separate review agent examines the patch with structured output: is the fix correct? Are there issues? Each finding has a priority, a title, and a detailed explanation.

If the reviewer says it's correct, the pipeline moves on. If it finds problems, the findings get fed back to the coder as context for the next iteration. The coder doesn't see its own previous attempt in isolation — it sees what the reviewer thought was wrong and addresses it specifically.

Between rounds, automated audit scripts check for rule violations and schema consistency. If the code breaks project conventions, that feedback enters the loop too.

Coder writes fix (from plan + prior review feedback)
  ↓
Audit scripts run (rules + schema checks)
  ↓
Review agent examines patch (structured JSON output)
  ↓
"patch is correct" → PASS → continue to sandbox
  ↓
Findings with priorities → FAIL → feed back to coder
  ↓
Repeat (up to 5 rounds)
  ↓
5 rounds exhausted → escalate to human with full context

This isn't "generate code and hope." It's a feedback loop where two independent AI agents converge on a correct solution through structured critique.

The Sandbox: A Production-Like World in 60 Seconds

For bugs that touch the UI, Bug Boomerang provisions an ephemeral test environment from scratch:

This entire environment — database branch, application stack, auth validation — spins up automatically, exists for exactly as long as the test needs it, and tears itself down afterward. No developer provisioned anything. No DevOps ticket was filed.

Escalation: Knowing When to Stop

Bug Boomerang doesn't pretend it can fix everything. It has explicit stop conditions:

When it escalates, the human gets everything: what was discovered, what was planned, what was coded, what the reviewer said, what the browser saw. Full context, not just "it didn't work."

And if a human posts a comment on the Linear issue while a run is active, Bug Boomerang treats it as new input. It supersedes the current run, starts fresh, and carries the human's feedback forward as additional context. The human doesn't need to learn a new interface — they just comment on the ticket like they normally would.

The Toolchain Is Pluggable

Every stage runs through a configurable toolchain. The agents, models, and providers are specified in config, not code:

toolchain:
  discovery:
    model: "claude-sonnet-4-5-20250929"
    provider: "anthropic"
  coder:
    model: "claude-opus-4-6"
    provider: "anthropic"
  review:
    model: "o3"
    provider: "openai"
    outputMode: "json"

Want to A/B test GPT-5.3-Codex against Claude Opus? Change a config value. Every tool also supports environment variable overrides: XENA_CODER_BIN, XENA_CODER_ARGS_JSON, XENA_CODER_TIMEOUT_MS. The pipeline doesn't care which model writes the code — it cares that the review loop produces correct output.

State Survives Everything

Every run is persisted to disk as a deterministic state machine. Every stage transition is recorded. Every agent output is saved as an artifact:

.xena/
  issues/{issueId}.json           # Run state machine
  artifacts/{issueId}/{runId}/    # Discovery, plan, review outputs
  sandbox-meta/{sandboxId}.json   # Environment metadata
  events.json                     # Dedup window (7-day)

If the server crashes mid-run, the state is there when it comes back. This isn't just crash recovery — it's auditability. You can trace exactly what happened at every stage of every run.

What Makes This Different

Tech Stack

How It Connects

Bug Boomerang shares DNA with the rest of the runtime family:

• Xena — the autonomous event operator. Bug Boomerang's webhook handling and state persistence patterns come from Xena's architecture.
• Noktua — the desktop agent. Same configurable toolchain philosophy — the framework is permanent, the components are variables.
• The coder/reviewer agents use the same pluggable model client pattern. When a better coding model ships, you change a string in config.

References

• Neon — Serverless Postgres with copy-on-write branching: neon.tech
• Vercel Sandbox — Ephemeral compute environments: Vercel docs
• Browser Use — Cloud browser automation: browser-use.com
• Linear — Issue tracking with webhook events: linear.app