The LLM Bug Report Template: How to Document AI Failures Your Team Can Actually Fix

Why LLM Bug Reports Are Different

In traditional software, a bug report contains enough information to reproduce the failure deterministically: exact inputs, exact steps, exact environment. The engineer runs it locally, sees the same failure, fixes the code, and confirms the fix. LLM failures do not work this way.

Non-determinism

The same prompt may produce different outputs each time it is run. A bug that appeared in a user session may not appear when you test it manually with the same input. This is not a bug in your logging; it is fundamental to how LLMs generate output.

Context sensitivity

The output depends heavily on what came before it in the conversation, the system prompt, the temperature and sampling settings, the model version, and even the time of day if the model provider is running different infrastructure. A report that only captures the user message is missing most of the context that determined the output.

Ambiguous failure criteria

In traditional software, a bug is a deviation from a specification. LLM failures often involve outputs that are plausible but wrong, factually incorrect but grammatically perfect, or biased in subtle ways that are hard to define precisely. The 'expected output' is often a judgment call, not a deterministic test.

Systemic vs. one-off failures

Some LLM failures are isolated to a specific user and input. Others are systematic: a failure mode that affects a whole class of queries, a demographic of users, or a topic area. A single bug report cannot tell you which you are dealing with. You need reproduction rate and affected volume data.

These differences mean your bug report template needs to capture context systematically, not just the surface-level failure. An AI bug report without the full context is not useful to an ML engineer trying to investigate it.

The Core Template

This template covers the minimum fields your LLM bug report needs. Adapt it to your tracking system (Jira, Linear, GitHub Issues, Notion) and your product's specific context.

CONTEXT

Date and time: [timestamp including timezone]

Model and version: [e.g., claude-sonnet-4-6, gpt-5.6-luna-20260801]

Product feature: [specific feature or workflow where the failure occurred]

User session ID: [for log lookup; redact PII as required]

Environment: [production / staging / dev]

FAILURE

Failure type: [hallucination / capability gap / bias / format error / refusal / safety / other]

Severity: [P0 = immediate harm risk / P1 = significant user impact / P2 = degraded experience / P3 = minor]

Observed output (exact):

[Paste the exact model output. Do not paraphrase.]

Expected output (describe, not prescribe):

[What should the model have done? Be specific about the quality dimension that failed: accuracy, completeness, tone, format, safety.]

Why this output is a failure:

[Explain, don't assume. Is it factually wrong? Does it violate your content policy? Does it fail the user task?]

FULL CONTEXT (required for investigation)

System prompt (exact or version number):

[The full system prompt active during this session, or a pointer to its version in your prompt registry]

Conversation history before the failure:

[All prior turns in the session, in order. This is essential. An LLM failure almost always depends on prior context.]

User input that triggered the failure (exact):

[The specific message that produced the bad output]

Temperature / sampling settings: [if configurable in your product]

Any injected context or retrieved documents: [RAG chunks, tool call results, injected variables]

REPRODUCTION AND SCOPE

Reproducible on re-run? [Yes / No / Sometimes]

Estimated reproduction rate: [e.g., 3 of 5 manual attempts, or unknown]

Is this likely isolated or systemic? [Is this a one-off or does the failure pattern likely affect a class of queries?]

Estimated affected users or sessions: [if queryable from logs]

INVESTIGATION NOTES

Hypothesis: [What do you think caused this? Prompt gap? Model capability limit? Edge case in retrieval?]

What was already tried: [prompt variations tested, workarounds attempted]

Suggested fix approach: [prompt update / fine-tuning / guardrail / model switch / feature change]

Linked tickets: [related bugs, feature requests, or model evaluations]

Failure Types: How to Classify What You Are Seeing

The "failure type" field in your bug report matters more than it looks. Different failure types have different root causes and different fix mechanisms. Classifying correctly points the investigation in the right direction.

Hallucination

What it is: The model stated something factually false with confidence. Distinguished from 'I don't know' failures because the model presented incorrect information as fact.

Investigation direction: Check whether the correct information was in the context (RAG retrieval failure) or whether the model has no reliable knowledge of the domain (model capability limit). The fix is usually improved retrieval or a grounding instruction, not fine-tuning.

Capability gap

What it is: The model understood the task correctly but could not complete it at the required quality level. Examples: poor code quality, weak reasoning on a complex multi-step problem, shallow summarization of a long document.

Investigation direction: Check whether a stronger model in your tier can do this task. If yes, this is a model selection issue. If no model can do it, this is a fundamental capability limit that requires scope reduction, human-in-the-loop design, or a different approach.

Format error

What it is: The model produced content in the wrong format (wrong JSON schema, wrong markdown structure, wrong length, missing required sections).

Investigation direction: Usually a prompt engineering fix. Add explicit format instructions, few-shot examples in the correct format, or use structured outputs/function calling to constrain the output schema.

Refusal

What it is: The model refused to complete a legitimate task, citing safety or policy concerns that were not warranted for the actual request.

Investigation direction: Review the system prompt and conversation context for ambiguity that may have triggered over-refusal. Rephrase the request context in the system prompt. If the model's safety training consistently refuses legitimate use cases, this may require a different model or explicit permissions.

Bias or tone failure

What it is: The output exhibited bias (demographic, political, cultural) or a tone that violates your product's voice guidelines. This includes outputs that are technically correct but written in a way that could harm or alienate users.

Investigation direction: Document specific language used. Tone failures are usually addressable via system prompt refinement and few-shot examples. Bias failures may require evaluation at scale to understand frequency before deciding on remediation.

Safety failure

What it is: The model produced content that causes real-world harm: dangerous instructions, personal information disclosure, content that violates laws or your Terms of Service. These are P0 by definition.

Investigation direction: Immediate escalation. Preserve the full log. Assess whether the failure is reproducible and whether it could affect other users. Engage your safety review process before any other action.

Build the Skills to Manage AI Products in Production

The AI PM Masterclass covers evaluation design, LLM failure modes, and how to work with ML teams to ship reliable AI products. September 2026 cohort.

Bug Triage: What to Fix First

AI bug triage differs from traditional software triage because a single high-severity AI failure may affect thousands of users simultaneously if it is systematic. Prioritize by both severity and scope.

P0: Fix immediately

Safety failures (harmful, illegal, or dangerous outputs). Any failure that could cause real-world harm to users or third parties. These go through your safety escalation path immediately regardless of reproduction rate.

P1: Fix in the current sprint

High-reproduction-rate failures that significantly degrade the core user task. Hallucinations on common queries. Refusals that block legitimate use cases. Format failures that break downstream integrations. Estimate affected user volume; high volume makes this more urgent.

P2: Fix in the next sprint or cycle

Failures that are low-reproduction or affect edge cases. Tone or style issues that are noticeable but not damaging. Capability gaps in secondary features. Document these carefully so they inform evaluation suite improvements.

P3: Backlog with evaluation tracking

Rare, isolated failures with no evidence of systemic pattern. Minor UX quality issues. Document these and route them to your evaluation suite so you can track whether they become more common over time.

The systemic vs. isolated distinction

Before triaging a bug, try to assess whether it is systemic. Run a query against your logs: how many sessions hit a similar pattern in the last 7 days? A failure that appeared once in user feedback may be appearing in 5% of sessions. That changes its priority entirely. Build a step into your triage process that queries production logs before severity is finalized.

Working with Engineers on LLM Bug Fixes

A good LLM bug report does not just document the failure. It sets up the engineer or ML practitioner to investigate it efficiently. A few practices that make the handoff work:

Always include the full conversation history

This is the most commonly missing field in AI bug reports. A user's message does not exist in isolation. The failure almost always depends on prior context in the session.

Include the exact system prompt or its version

If your team tracks prompt versions (which you should), reference the version. If not, paste the full system prompt. Engineers cannot diagnose prompt-related failures without knowing what the model was instructed to do.

Distinguish between 'this happened once' and 'this is a pattern'

Tell the engineer whether you have evidence of frequency. A report that says 'I saw this once' is investigated differently from 'this appeared in 200 session logs this week.' Include your log query if you ran one.

Suggest a fix hypothesis, but hold it loosely

Your hypothesis is a starting point, not an instruction. Engineers and ML practitioners often find that the actual root cause is different from the surface-level guess. A hypothesis is useful; a prescription is constraining.

Define done before investigation starts

What does a fix look like? If you define success criteria upfront (the model should now do X, and you have test cases to verify it), the engineer can confirm the fix with a concrete pass/fail, not just a gut check.

The Template in Use: Three Common Scenarios

Scenario A: Hallucination in a customer-facing FAQ bot

What happened: The bot confidently stated the wrong return policy. The correct policy is 30 days; the model said 14 days.

What to capture: Full conversation history before the error, the exact user question, the system prompt (which should include the return policy). Check: was the correct policy in the system prompt? If yes, why did the model ignore it? If no, this is a retrieval failure, not a model failure.

Fix direction: Add the correct policy explicitly to the system prompt or improve RAG retrieval for policy documents. Add a test case to your regression suite that verifies return policy accuracy.

Scenario B: Refusal on a legitimate enterprise writing task

What happened: A legal drafting tool refused to generate an indemnification clause, citing 'legal advice' concerns, even though the system prompt explicitly defines the tool as a drafting assistant for licensed attorneys.

What to capture: The exact user request, the full system prompt, conversation history. The system prompt is almost certainly the key: was it clear enough that the model is operating in a professional legal context?

Fix direction: Strengthen the system prompt with explicit context about the professional user and use case. Consider adding a few-shot example of a similar task completed successfully. Test with a range of legal drafting requests to confirm the fix does not introduce other refusals.

Scenario C: Inconsistent output format breaking a downstream pipeline

What happened: The model is supposed to return JSON with a specific schema. Approximately 3% of responses return malformed JSON or include narrative text before the JSON block.

What to capture: Sample of the malformed outputs, the prompt instruction for JSON formatting, whether structured outputs or function calling is in use. A 3% failure rate in a pipeline is significant at scale.

Fix direction: Switch to structured outputs or function calling if not already in use. These constrain the model to valid JSON schema and eliminate format failures. If structured outputs are unavailable, add explicit few-shot examples of the correct JSON format and a validator that retries on malformed output.