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.

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.

Workflow

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

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

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

Related Resources

Explore more resources that work well with this one.