Engineering

Bug Investigation Template

A reusable bug investigation template with variables for symptom, environment, reproduction steps, expected and actual behavior, error logs, and affected version.

Open in Prompt Template Builder

Overview

Debugging without structure leads to overlooked causes, wasted time, and incomplete fixes. This template captures everything the AI model needs to reason about a bug: the observed symptom, the environment it appeared in, exact reproduction steps, the divergence between expected and actual behavior, and any relevant error output. The output is an ordered list of likely root causes with diagnostic confirmation steps — not guesses.

How to use this resource

Open in Prompt Template Builder

Load the template. Variables auto-detected: symptom, affectedVersion, environment, reproductionSteps, expectedBehavior, actualBehavior, errorMessages, additionalContext.
Fill in what you know

Paste the error message verbatim, describe the environment precisely (OS, browser, server version), and write out the reproduction steps as numbered steps.
Be precise about the divergence

The most important variables are expectedBehavior and actualBehavior — describe them with specific values, not general descriptions like 'it didn't work'.
Run with the filled preview

Paste the filled preview into your AI tool alongside any relevant code snippets. The structured context helps the model reason from evidence rather than speculation.

Why This Works

Separating expected from actual behavior forces explicit articulation of the contract violation — the single most important signal for root cause analysis
Including reproduction steps prevents the AI from reasoning about hypothetical conditions rather than the actual failure
Requesting root causes ordered by probability, not a flat list, forces the model to reason about likelihood rather than listing every remote possibility
The regression risk section surfaces the fix's blast radius before any code is changed

Best for

Bugs with clear symptoms but unclear causes
Environment-specific failures (works on local, fails in staging)
Bugs where logs exist but are hard to interpret without context
Handoffs where the developer who found the bug isn't the one fixing it

Not for

Performance profiling — use a dedicated profiler instead
Intermittent bugs with no reproduction steps — gather more data first
Security vulnerabilities — those require a separate disclosure process

Use cases

Investigating a production bug with logs before diving into the codebase
Documenting a bug report in a structured format for a team handoff
Running AI-assisted triage on incoming support tickets with reproduction steps
Preparing for a debugging session by externalizing all known facts

FAQ

Which variables in the bug investigation template matter most?

The {{expectedBehavior}} and {{actualBehavior}} pair: the workflow calls them the most important, since separating them forces an explicit statement of the contract violation, and asks you to fill them with specific values, not "it didn't work". The Prompt Template Builder auto-detects all eight variables; you fill the preview, paste it into your AI tool with any code, and own the diagnosis it returns.

Which outputs does the filled bug-investigation template ask the AI to produce?

Four numbered outputs: likely root causes ordered by probability with brief reasoning, diagnostic steps to confirm the most likely one, a suggested fix with explanation, and the regression risk. Ordering causes by probability rather than a flat list pushes the model to reason about likelihood. The Prompt Template Builder fills the variables; you run the preview in your own assistant and verify the fix.

Customize This Resource

Opens the pre-filled template in Prompt Template Builder. Review the variables, add sample values, and build your output.

Open in Prompt Template Builder

Prompt Template

Copy it as-is, or use Open in Prompt Template Builder to load it pre-filled and customize it with your own context.

Investigate the following bug.

Symptom: {{symptom}}

Affected version: {{affectedVersion}}

Environment:
{{environment}}

Steps to reproduce:
{{reproductionSteps}}

Expected behavior:
{{expectedBehavior}}

Actual behavior:
{{actualBehavior}}

Error messages or logs:
{{errorMessages}}

Additional context:
{{additionalContext}}

Provide:
1. Likely root causes ordered by probability, with brief reasoning for each
2. Diagnostic steps to confirm the most likely cause
3. Suggested fix with explanation
4. Regression risk — what else could break if this is changed

Variables in this template

{{symptom}} {{affectedVersion}} {{environment}} {{reproductionSteps}} {{expectedBehavior}} {{actualBehavior}} {{errorMessages}} {{additionalContext}}

More resources from Prompt Template Builder

Resource

Agent Task Template

A reusable AI agent task template with variables for objective, context, available tools, constraints, success criteria, failure handling, and output format.

AI Agents

Resource

Blog Post Template

A reusable long-form content template with variables for topic, audience, tone, target keyword, content angle, outline, and call to action.

Content

Resource

Pull Request Review Template

A reusable PR review prompt template with variables for repository, branch, change summary, changed files, review criteria, and risk areas.

Engineering

Resources that pair well

Resource

Bug Triage Assistant

Convert scattered bug notes, Slack messages, or user complaints into structured engineering tasks with reproduction steps, severity, and root cause hypothesis.

Engineering

Resource

API Request Variable Builder

Turns a reusable API request prompt into a clean variable set covering endpoint, method, auth, payload, response format, and error handling.

Engineering

Related tools

Tool

Prompt Template Builder

Build reusable prompt templates with {{variable}} placeholders, live preview, and export.

Prompt Builders

Tip: Save time by exploring related resources and tools that integrate with this resource.