Bug Fix Decomposition Prompt for Coding Agents

This prompt is designed for coding agents that receive a bug report and must produce a structured diagnostic and fix plan before modifying any code. The core job-to-be-done is to force the agent to isolate the bug's root cause, propose candidate fix locations, define verification steps, and specify regression tests—all before a single line of code changes. This pre-execution plan serves as a reviewable artifact that a developer can inspect, challenge, and approve, reducing the risk of an agent making scattered, untargeted edits that introduce new regressions. The ideal user is an engineering lead or developer integrating an AI coding agent into a production repository where untrusted code changes are unacceptable without prior reasoning.

Use this prompt when the bug is reproducible or well-described but its root cause is unknown, when multiple files or modules could be involved, or when the fix requires careful verification to avoid side effects. It is particularly valuable in regulated or high-reliability codebases where every change must be traceable to a diagnosed cause. The prompt expects a detailed bug report as input—stack traces, reproduction steps, logs, and affected versions—and outputs a decomposition with root-cause investigation steps, candidate fix locations, verification subtasks, and regression test requirements. Do not use this prompt for feature requests, architectural redesigns, or trivial one-line fixes where the cause is already obvious. It is also inappropriate for tasks where the agent lacks access to the repository context needed to identify specific files or modules.

Before wiring this prompt into your agent harness, ensure you have a mechanism to supply the bug report as structured context and to validate that the output plan contains all required sections: investigation steps, fix candidates, verification, and regression tests. If the agent's plan skips root-cause isolation and jumps directly to a code change, the harness should reject the output and request a revised plan. In high-risk environments, route the generated plan to a human reviewer before the agent is authorized to execute any code edits. This prompt is a planning gate, not a fix generator—treat it as a required checkpoint in your agent's execution loop.

This prompt template is designed to be pasted directly into your agent harness. It instructs a coding agent to take a raw bug report and produce a structured plan that isolates the root cause before attempting any fixes. The template uses square-bracket placeholders for all dynamic inputs, ensuring you can adapt it to your specific repository, bug tracker, and coding standards without modifying the core logic. Before using this prompt, ensure your agent has access to the necessary tools, such as file reading, code search, and a test runner.

textCopy
You are a methodical debugging agent. Your task is to analyze a bug report and produce a structured diagnostic and fix plan. Do not write any code yet. Your goal is to understand the bug completely before proposing a solution.

**Bug Report:**
[TITLE]: [BUG_TITLE]
[DESCRIPTION]: [BUG_DESCRIPTION]
[STEPS_TO_REPRODUCE]: [REPRODUCTION_STEPS]
[OBSERVED_BEHAVIOR]: [OBSERVED_RESULT]
[EXPECTED_BEHAVIOR]: [EXPECTED_RESULT]
[ENVIRONMENT]: [ENVIRONMENT_DETAILS]

**Repository Context:**
[REPOSITORY_MAP]: [A summary of the repository's file tree and key modules]

**Available Tools:**
[TOOLS]: [List of available tools, e.g., 'read_file', 'search_code', 'run_tests']

**Output Schema:**
Produce a JSON object with the following structure. Do not include any text outside the JSON object.
{
  "problem_statement": "A one-sentence summary of the bug.",
  "root_cause_hypotheses": [
    {
      "hypothesis": "A clear statement of a potential root cause.",
      "confidence": "low|medium|high",
      "investigation_steps": ["Step 1 to validate this hypothesis", "Step 2..."]
    }
  ],
  "diagnostic_plan": [
    {
      "step_id": 1,
      "action": "A specific, executable action using available tools, e.g., 'search_code for the error message'.",
      "expected_result": "What you expect to find if this step is successful.",
      "purpose": "How this step helps isolate the root cause."
    }
  ],
  "candidate_fix_locations": [
    {
      "file_path": "The relative path to the file.",
      "function_or_component": "The specific function or component.",
      "rationale": "Why this location is a candidate for the fix."
    }
  ],
  "verification_plan": [
    {
      "step_id": 1,
      "action": "A specific action to verify the fix, e.g., 'run the test suite for the user module'.",
      "expected_result": "The expected outcome that confirms the fix."
    }
  ],
  "regression_risk_areas": ["Module A", "Feature B"],
  "required_tests": [
    {
      "type": "unit|integration|e2e",
      "description": "A description of the test to be added or modified.",
      "target_file": "The file where the test should live."
    }
  ]
}

**Constraints:**
[CONSTRAINTS]: [E.g., 'Do not modify database schemas.', 'All fixes must be backwards compatible.', 'Prioritize the hypothesis with the highest confidence first.']

To adapt this template, replace each square-bracket placeholder with data from your bug tracking system and agent context. The [REPOSITORY_MAP] is critical for grounding the agent; provide a concise summary of the codebase structure. The [TOOLS] list must exactly match the functions your agent harness exposes. The [CONSTRAINTS] section is your primary lever for enforcing safety and policy, such as preventing database changes or requiring human approval for certain file modifications. After the agent returns the JSON plan, your harness should validate it against the schema before allowing the agent to proceed to the execution phase.

The Bug Fix Decomposition prompt is designed to be the first step in a coding agent's fix workflow, transforming an unstructured bug report into a structured, verifiable plan. It should be invoked immediately after a bug is triaged and assigned, before any file is read or edited. The prompt's output is a JSON plan that serves as the contract for downstream execution steps: root-cause investigation, candidate fix location, verification, and regression testing. The harness must enforce that the agent does not skip to code changes before the decomposition is complete and validated.

To integrate this prompt, wrap it in a function that accepts the bug report text, repository context (file tree, recent commits, relevant logs), and any known constraints (e.g., 'do not modify the database schema'). The function should call a capable model (such as GPT-4o or Claude 3.5 Sonnet) with a low temperature (0.0–0.2) to maximize deterministic planning. The output must be parsed as JSON and validated against a strict schema: the plan must contain root_cause_hypotheses (array of objects with hypothesis, evidence, investigation_steps), candidate_fix_locations (array of file paths with reasoning), verification_steps (ordered list of manual or automated checks), and regression_test_requirements (list of test cases to add or run). If parsing fails, retry once with a stronger format instruction; if it fails again, log the raw output and escalate for human review. This is a high-stakes workflow—an incorrect fix plan can introduce new bugs—so never silently proceed with a malformed plan.

After validation, the harness should store the plan as a structured artifact in the agent's state, keyed by the bug ID. Each step in the plan should be executed by a separate tool-calling agent that reads files, runs diagnostic commands, or applies patches, but only within the boundaries defined by the decomposition. Implement a state machine that tracks which investigation steps are complete, which hypotheses are confirmed or rejected, and whether the verification steps pass before marking the fix as resolved. Log every transition, including model inputs, outputs, and tool calls, to enable traceability and post-mortem analysis. Avoid the temptation to let the agent 'fix while investigating'—the decomposition prompt's primary value is enforcing diagnostic discipline before action.