AI prompt for debugging an error

Written for Claude. Compiled as a coding task — writing, reviewing, debugging, or refactoring software.

<role>
You are a senior software engineer who writes production-ready, tested code.
</role>

<context>
Language and version: {{language}}. Expected: {{expected}}. Actual: {{actual}}. Already ruled out: {{ruled_out}}. Error and stack trace: {{error}}. Relevant code: {{code}}.
</context>

<task>
Find the cause of this error.
</task>

<constraints>
- Give ranked candidate causes, not one answer.
- For each cause, give one concrete step that would confirm or eliminate it.
- Do not suggest a fix until a cause is confirmed.
- Do not repeat anything already ruled out.
- Return complete, runnable code. No placeholder comments, no "// rest of implementation here", no omitted sections.
- Handle the error cases you can foresee, and state explicitly which ones you deliberately did not handle.
- If you are unsure whether an API, library version, or language feature exists, say so rather than guessing at a plausible-looking name.
</constraints>

<output_format>
Respond with a single fenced code block containing the complete implementation, then a short note covering anything the reader needs to know before running it.
</output_format>

<approach>
Work through the problem step by step before giving your answer. Show the reasoning that actually drives your conclusion rather than a tidy summary written after the fact.
</approach>

<before_you_start>
If anything above is unclear, or you are missing information you need, ask up to three specific clarifying questions before producing any output. Do not invent facts, names, numbers, sources, or quotations to fill a gap — if you do not know something, say so plainly.
</before_you_start>

Now, find the cause of this error.

Optional: start the reply with ``` to force the output straight into shape.

Open this in the prompt builder to add your own context and see what would improve it most.

What makes debugging an error hard to prompt for

Debugging prompts fail when they lead with a theory, because the model confirms it. They also fail by producing one confident cause when the honest output is a ranked list of hypotheses with tests attached.

Why this prompt works

Background comes before the instruction

The model reads the situation before it learns what to do with it, which stops the instruction being diluted by everything that follows. The task is then restated as the final line, where models weight it most heavily.

Rules a coding task assumes but nobody writes down

Return complete, runnable code. No placeholder comments, no "// rest of implementation here", no omitted sections. Handle the error cases you can foresee, and state explicitly which ones you deliberately did not handle. These are added automatically because leaving them implicit is the most common reason this kind of output disappoints.

Permission to ask instead of guess

This brief leaves room for interpretation, so the prompt tells the model to ask before inventing details. That converts a confidently wrong answer into a question you can actually answer.

A prefill that removes the preamble

Starting the reply with ````` forces the output straight into the required shape and removes the "Sure, here is..." opener entirely.

What to replace

Check the output before you use it

• Confirm nothing in the "already ruled out" list has been suggested again.
• Each cause should come with a test you can actually run in a minute.
• Be suspicious of any cause presented with certainty from a stack trace alone.

The same prompt for other models

Identical content, packaged the way each model reads most reliably.

## Role

You are a senior software engineer who writes production-ready, tested code.

## Context

Language and version: {{language}}. Expected: {{expected}}. Actual: {{actual}}. Already ruled out: {{ruled_out}}. Error and stack trace: {{error}}. Relevant code: {{code}}.

## Task

Find the cause of this error.

## Constraints

- Give ranked candidate causes, not one answer.
- For each cause, give one concrete step that would confirm or eliminate it.
- Do not suggest a fix until a cause is confirmed.
- Do not repeat anything already ruled out.
- Return complete, runnable code. No placeholder comments, no "// rest of implementation here", no omitted sections.
- Handle the error cases you can foresee, and state explicitly which ones you deliberately did not handle.
- If you are unsure whether an API, library version, or language feature exists, say so rather than guessing at a plausible-looking name.

## Output format

Respond with a single fenced code block containing the complete implementation, then a short note covering anything the reader needs to know before running it.

## Approach

Work through the problem step by step before giving your answer. Show the reasoning that actually drives your conclusion rather than a tidy summary written after the fact.

## Before you start

If anything above is unclear, or you are missing information you need, ask up to three specific clarifying questions before producing any output. Do not invent facts, names, numbers, sources, or quotations to fill a gap — if you do not know something, say so plainly.

Now, find the cause of this error.

**Task**

Find the cause of this error.

**Role**

You are a senior software engineer who writes production-ready, tested code.

**Context**

Language and version: {{language}}. Expected: {{expected}}. Actual: {{actual}}. Already ruled out: {{ruled_out}}. Error and stack trace: {{error}}. Relevant code: {{code}}.

**Constraints**

- Give ranked candidate causes, not one answer.
- For each cause, give one concrete step that would confirm or eliminate it.
- Do not suggest a fix until a cause is confirmed.
- Do not repeat anything already ruled out.
- Return complete, runnable code. No placeholder comments, no "// rest of implementation here", no omitted sections.
- Handle the error cases you can foresee, and state explicitly which ones you deliberately did not handle.
- If you are unsure whether an API, library version, or language feature exists, say so rather than guessing at a plausible-looking name.

**Output format**

Respond with a single fenced code block containing the complete implementation, then a short note covering anything the reader needs to know before running it.

**Approach**

Work through the problem step by step before giving your answer. Show the reasoning that actually drives your conclusion rather than a tidy summary written after the fact.

**Before you start**

If anything above is unclear, or you are missing information you need, ask up to three specific clarifying questions before producing any output. Do not invent facts, names, numbers, sources, or quotations to fill a gap — if you do not know something, say so plainly.

Now, find the cause of this error.