# AI Bug-Fix & Draft-PR Agent

> An AI bug-fix agent: reproduces an issue, finds root cause, writes a minimal fix plus tests, and opens a focused draft PR — sandboxed, small-diff, human-gated.

- **Category:** Software Engineering
- **Difficulty:** Advanced
- **Setup time:** 50 min
- **Stacks:** Claude, LangGraph, OpenAI
- **Version:** 2.0.0 (updated 2026-06-21)
- **Source:** https://agent-kits.com/kit/issue-to-pr-planner

## Overview

Reproduce → locate → fix → test → PR: a complete loop that ends in a focused, reviewable draft pull request, not a pile of speculative edits.

Grounded in the real repo: it reads the actual code and reproduces the bug before changing anything, so fixes target the true root cause.

Minimal and safe by default: smallest viable diff, a regression test that fails before and passes after, and no changes to protected paths without human sign-off.

Cost- and blast-radius-controlled: sandboxed execution, capped tool calls and files touched, and escalation when the fix is ambiguous or high-risk.

## When to use it

- You have a backlog of well-described, reproducible bugs that follow common patterns and drain senior time.
- Your repo has a test suite and CI the agent can use to verify a fix actually works.
- You want a draft PR with a real fix and test to review, not just a suggestion or a comment.
- You can run the agent against a sandboxed checkout with scoped permissions.
- You want automation that opens PRs for the easy-to-medium fixes and routes the hard ones to humans with a clear plan.

## When not to use it

- The bug report has no reproduction steps and the failure cannot be reproduced — the agent should ask or escalate, not invent a fix.
- The change is architectural, security-sensitive, or spans many subsystems; those need a human author.
- You have no tests or CI, so a fix cannot be verified before it is proposed.
- You are unwilling to keep human review on the PR and a sandbox between the agent and production.

## Architecture

- **Issue intake** — Pulls the issue/bug report and any linked logs, stack traces, or failing CI runs, and normalizes them into a structured task with an explicit acceptance criterion (the bug no longer happens).
- **Sandboxed checkout** — Clones the repo at the target branch into an isolated sandbox with scoped, least-privilege credentials. All execution happens here — never against production or with broad tokens.
- **Reproduction harness** — Attempts to reproduce the bug via an existing test, a new failing test, or the documented steps. No code is modified until a reproduction exists or the agent gives up and asks.
- **Root-cause search** — Uses semantic + symbol search to trace the failure to its source, reading only the relevant files and citing the responsible lines as evidence for the fix.
- **Fix & test engine** — The model produces the minimal patch and a regression test, then runs the failing test (now passing) plus the surrounding suite and static analysis to catch regressions.
- **Policy & escalation gate** — A deterministic gate checks changed paths against protected areas, enforces the file/diff budget, and requires a passing regression test before a PR can be opened; violations force ESCALATE.
- **PR publishing & feedback** — Opens a draft PR with the diff, test, explanation, and risks. Reviewer accept/edit/reject outcomes are logged to tune which bug classes are safe to automate.

## Files in this bundle

- `system-prompt.md` — the agent's system prompt
- `tools.json` — tool/function definitions the agent expects
- `workflow.md` — step-by-step run loop
- `.env.example` — environment variables to fill in
- `kit.json` — full structured metadata
- `starters/` — minimal starter snippets
- `LICENSE` — Apache-2.0 (code, configuration, and schema)
- `LICENSE-CONTENT` — CC BY 4.0 (specification text and documentation)
- `NOTICE` — attribution and trademark notice
- `run.py` — **runnable demo**: real agent loop with mock tools (`pip install anthropic`, set `ANTHROPIC_API_KEY`, `python run.py`)
- `agentaz.json` / `agentaz.schema.json` — AgentAz™ governance spec + schema

## Implementation notes

- Make 'a regression test that fails before and passes after' a hard merge requirement — it is the single best guard against speculative or wrong fixes.
- Run everything in a sandbox with a least-privilege, single-repo token. The agent should never hold broad credentials or touch production.
- Enforce protected paths and the diff budget in a deterministic gate, not just the prompt; any violation downgrades to ESCALATE with a plan.
- Start with --dry-run and label-gated triggers so a human chooses which issues the agent attempts; expand the allowed bug classes as merge rates prove out.
- Keep diffs tiny on purpose. Small, single-cause PRs are easy to review and safe to merge; reject the urge to bundle cleanups.
- Log merged/edited/rejected outcomes per bug class. Rejection patterns tell you exactly where to tighten the prompt or stop auto-attempting.
- A cheaper model is usually enough to triage and search, so keep the strong model for root-cause reasoning and patch generation.

## Variations

- **Basic — Plan & patch suggester:** Reproduces and diagnoses the bug and posts a proposed patch + test as an issue comment for a human to apply. No branch, no PR — the safest starting point.
- **Advanced — Draft-PR author:** Opens a draft PR with the minimal fix and a passing regression test, gated by protected paths, a diff budget, and a required green test run before the PR is created.
- **Enterprise — Governed fleet fixer:** Runs across many repos with per-repo policies and CODEOWNERS routing, sandboxed execution, secret-scanning, full audit trails, and a feedback loop that tunes which bug classes auto-open PRs.

## FAQ

**Will it merge code on its own?**

No. It opens a DRAFT pull request with the fix and a passing regression test; a human reviews and merges. It never commits to main or force-pushes.

**How does it avoid shipping a wrong fix?**

It must reproduce the bug with a failing test before changing anything, and the fix must make that test pass without breaking the suite. If it can't reproduce or isn't confident, it asks for info or escalates instead of guessing.

**What stops it from making sweeping changes?**

A deterministic diff budget and protected-path gate. It can only touch a small number of files, can't modify auth/payments/migrations/infra, and escalates with a plan when a fix would exceed those bounds.

**Is it safe to run on our codebase?**

It runs in an isolated sandbox with a least-privilege, single-repo token, never executes untrusted code outside the sandbox, and flags (without echoing) any secret it encounters.

**What kinds of bugs is it good at?**

Well-described, reproducible bugs that follow common patterns — null/None handling, off-by-one, validation gaps, simple logic errors. Architectural or security-sensitive changes are routed to humans.

**How do we control cost?**

It searches before reading, caps tool calls and files per issue, and uses a cheaper model for triage with the strong model reserved for root-cause analysis and the patch.


---

© 2026 AgentKits · www.agent-kits.com

**Open source.** Code, configuration, and the AgentAz™ schema are licensed under
**Apache-2.0**; specification text and documentation under **CC BY 4.0** (with
attribution to AgentKits, link to https://www.agent-kits.com). See LICENSE, LICENSE-CONTENT,
and NOTICE in this bundle. "AgentAz" and "AgentKits" are trademarks of AgentKits.

**Flagship reference blueprint.** View the source, AgentAz™ spec, and frozen v1.0 schema
in the public registry: https://github.com/agent-kits/agentaz
Original: https://agent-kits.com/kit/issue-to-pr-planner
