Bug Triage Chain-of-Thought Prompt Template

This prompt is for engineering teams that need to triage incoming bug reports systematically. It teaches the model a structured reasoning pattern through worked examples, producing a severity assessment, root cause hypotheses, and reproduction steps. Use it when you have a bug description and need a consistent, auditable triage artifact before a human engineer picks up the ticket. The primary job-to-be-done is transforming a messy, often incomplete user report into a standardized engineering brief that reduces the cognitive load on the on-call developer and ensures every ticket is evaluated against the same criteria.

The ideal user is a technical lead, engineering manager, or platform engineer integrating an AI triage step into an issue-tracking system like Jira, Linear, or GitHub Issues. The required context includes a bug title, a free-text description, and relevant system context such as the affected service, environment, and recent deployments. The prompt is most effective when the bug report contains at least one observable symptom, even if the root cause is unknown. It is not a replacement for a human when the report is a vague complaint with no actionable details, such as 'the app is broken.' In that case, the correct action is to request more information from the reporter, not to force a hallucinated triage.

Do not use this prompt for live incident response where seconds matter and a human is already in the war room. It is also unsuitable for bugs that require access to a running system to diagnose, such as inspecting live logs, querying a database, or profiling a memory leak. The prompt's reasoning is based solely on the text provided; it cannot run tools or access real-time telemetry. Finally, avoid using this prompt when the bug report contains sensitive user data that should not be sent to a third-party model. In such cases, redact the PII before invoking the prompt or use a local, private deployment. The next section provides the copy-ready template you can adapt for your own issue tracker.

This template uses few-shot demonstrations to teach the model a structured bug triage reasoning pattern. The worked examples show the desired depth of analysis—severity assessment, root cause hypothesis generation, and reproduction step construction—before the model processes the target bug. The square-bracket placeholders let you swap in your own bug report format, severity definitions, and output schema without rewriting the reasoning instructions.

textCopy
You are a systematic bug triage analyst. For each bug report, you will reason step by step through severity assessment, root cause hypotheses, and reproduction steps before producing a structured output.

Follow this reasoning pattern for every bug:
1. Extract the observable symptoms and impact from the report.
2. Map symptoms to possible subsystems or components.
3. Assess severity against the defined criteria, explaining why each criterion applies or does not apply.
4. Generate root cause hypotheses ranked by likelihood, with evidence from the report for each.
5. Construct minimal reproduction steps that would confirm or rule out the leading hypothesis.
6. Identify missing information that would change your assessment.

---

[Bug Report Example 1]
Title: [EXAMPLE_TITLE_1]
Description: [EXAMPLE_DESCRIPTION_1]
Environment: [EXAMPLE_ENVIRONMENT_1]

Triage Reasoning:
Observable Symptoms and Impact: [WORKED_SYMPTOMS_1]
Subsystem Mapping: [WORKED_SUBSYSTEMS_1]
Severity Assessment: [WORKED_SEVERITY_1]
Root Cause Hypotheses (ranked): [WORKED_HYPOTHESES_1]
Reproduction Steps: [WORKED_REPRO_STEPS_1]
Missing Information: [WORKED_MISSING_1]

Structured Output:
[WORKED_OUTPUT_1]

---

[Bug Report Example 2]
Title: [EXAMPLE_TITLE_2]
Description: [EXAMPLE_DESCRIPTION_2]
Environment: [EXAMPLE_ENVIRONMENT_2]

Triage Reasoning:
Observable Symptoms and Impact: [WORKED_SYMPTOMS_2]
Subsystem Mapping: [WORKED_SUBSYSTEMS_2]
Severity Assessment: [WORKED_SEVERITY_2]
Root Cause Hypotheses (ranked): [WORKED_HYPOTHESES_2]
Reproduction Steps: [WORKED_REPRO_STEPS_2]
Missing Information: [WORKED_MISSING_2]

Structured Output:
[WORKED_OUTPUT_2]

---

Now triage the following bug report using the same reasoning pattern.

[Bug Report]
Title: [BUG_TITLE]
Description: [BUG_DESCRIPTION]
Environment: [BUG_ENVIRONMENT]

[SEVERITY_CRITERIA]

[OUTPUT_SCHEMA]

[CONSTRAINTS]

Adapt this template by replacing the example blocks with real bugs from your own tracker that demonstrate the reasoning depth you expect. Include at least one example where severity is ambiguous and one where the root cause is non-obvious—these teach the model to avoid premature conclusions. The [SEVERITY_CRITERIA] placeholder should contain your team's actual severity definitions (e.g., S1: data loss, S2: blocked workflow, S3: workaround exists). The [OUTPUT_SCHEMA] placeholder should specify the exact JSON or markdown structure your ticketing system expects. The [CONSTRAINTS] placeholder is where you add rules like "never assign S1 without data loss evidence" or "require reproduction steps for S1 and S2 only."

Before shipping, validate this prompt against a golden set of 10-20 bugs with known triage outcomes. Check for three failure modes: missed severity signals where the model under-classifies because symptoms span multiple report fields, premature root cause conclusions where the model latches onto the first plausible cause without exploring alternatives, and hallucinated reproduction steps that reference UI elements or API endpoints not mentioned in the report. If your bug tracker has a severity field, compare model-assigned severity against historical human assignments and investigate any systematic divergence. For production use, log the full reasoning trace alongside the structured output so that triage decisions remain auditable and correctable when the model gets it wrong.

The Bug Triage Chain-of-Thought prompt is designed to be integrated into an engineering workflow, not used as a one-off chat. The harness should accept a bug report as input, inject it into the [BUG_REPORT] placeholder, and parse the structured output for downstream routing. Because the prompt produces a severity assessment, root cause hypotheses, and reproduction steps, the harness must validate that all required fields are present and that the severity level matches a predefined enum before the output is accepted. This is not a conversational prompt; it should be called as a single-turn completion or with a strict system message that prevents the model from asking clarifying questions unless explicitly instructed by the [CLARIFICATION_POLICY] variable.

The implementation should include a validation layer that checks the model's output against the expected schema. For severity, confirm the value is one of the allowed levels (e.g., critical, high, medium, low, cosmetic). For root cause hypotheses, verify that each entry contains a hypothesis string and a confidence score between 0.0 and 1.0. If validation fails, the harness should retry with a repair prompt that includes the original input, the failed output, and the specific validation errors. Limit retries to a maximum of 2 attempts before escalating to a human review queue. Log every attempt, including the raw prompt, the model's response, validation errors, and the final accepted or escalated status, for auditability and prompt debugging. Use a model with strong reasoning capabilities (such as GPT-4o, Claude 3.5 Sonnet, or Gemini 1.5 Pro) and set temperature to 0.2 or lower to maximize deterministic, structured output.

For high-severity bugs (critical or high), the harness should automatically route the triage result to a human review queue before any automated actions are taken, such as creating a P0 incident or paging an on-call engineer. The [HUMAN_REVIEW_THRESHOLD] variable in the prompt template should be set to match your team's escalation policy. Avoid wiring this prompt directly to automated incident creation without a human-in-the-loop gate. The harness should also track the reproduction_steps field: if it is empty or contains a placeholder like 'Unable to determine,' flag the triage for manual reproduction by a QA engineer. This prevents the system from closing or deprioritizing bugs that the model could not fully analyze. Finally, store the validated triage output in your bug tracker as a structured comment or custom field, not as freeform text, so that downstream dashboards and metrics can consume the data reliably.