Troubleshooting Decision Tree Prompt

This prompt is designed for support engineers and platform teams who need to transform a static, flat catalog of error codes into an interactive, branching diagnostic flow. The core job-to-be-done is converting a reference list—where each entry is an isolated error—into a navigable decision tree that guides a user or an automated system from a symptom to a specific root cause and resolution. The ideal user has a complete or near-complete error code catalog and needs a structured troubleshooting script that can be used by Tier 1 support agents, embedded into a support chatbot, or integrated into a runbook automation system. The required context includes the full list of error codes, their descriptions, and any known common causes or diagnostic commands.

You should use this prompt when the error catalog is large enough that a simple lookup table is insufficient, typically more than 20-30 distinct error codes with overlapping symptoms. The prompt excels at identifying shared diagnostic checkpoints—such as 'verify network connectivity' or 'check configuration file syntax'—that can be reused across multiple branches, reducing redundancy in the final script. It also includes a critical coverage validation step: the prompt instructs the model to verify that every single error code from the input catalog appears in at least one terminal resolution leaf. This prevents orphaned errors that would otherwise be unreachable in the decision tree. The output is a structured tree with three node types: branching questions (yes/no or multiple-choice), diagnostic checkpoints (commands to run or states to verify), and terminal resolution leaves (mapped to specific error codes with fix steps).

Do not use this prompt when you need a simple error code lookup table or a flat FAQ. If your error catalog has fewer than 10 codes with no overlapping symptoms, a decision tree adds unnecessary complexity. Similarly, avoid this prompt when the error codes lack sufficient diagnostic context—if you cannot describe what conditions lead to each error, the model cannot infer meaningful branching logic. For high-risk production systems where an incorrect diagnostic path could trigger destructive actions (like database resets or traffic rerouting), you must add a human review gate after generation and before deployment. The prompt produces a troubleshooting guide, not a verified runbook; always have a subject-matter expert validate the diagnostic commands and resolution steps before they reach production.

This prompt template is designed to transform a structured list of error codes into an interactive diagnostic decision tree. The model acts as a support engineering architect, building a branching logic flow that starts from a reported error code and guides a technician through diagnostic checkpoints to a terminal resolution leaf. The template uses square-bracket placeholders that you must replace with your specific error catalog, output format requirements, and operational constraints before sending it to the model.

markdownCopy
You are a senior support engineer designing an interactive diagnostic decision tree for a production API. Your task is to convert the provided error code catalog into a branching troubleshooting flow that a support technician can follow step-by-step.

## INPUT ERROR CATALOG
[ERROR_CATALOG]

## OUTPUT SCHEMA
Produce a decision tree in [OUTPUT_FORMAT] format. Each node must be one of:
- `question`: A diagnostic question with a set of `branches` keyed by possible answers.
- `checkpoint`: A verification step that produces a pass/fail result, with `pass_branch` and `fail_branch`.
- `resolution`: A terminal leaf containing the root cause summary and numbered resolution steps.

## CONSTRAINTS
- Every error code in [ERROR_CATALOG] must map to at least one resolution leaf.
- Include prerequisite checks (e.g., "Verify authentication token is valid") before deeper diagnostics.
- For any resolution step that is destructive or irreversible (e.g., "drop and recreate the index"), prefix it with `[CONFIRM]` and require explicit user confirmation.
- For errors related to rate limiting (HTTP 429), include a branch that checks the `Retry-After` header and calculates a backoff.
- If a diagnostic path cannot reach a resolution, terminate at a `resolution` node that instructs the technician to escalate with a specific summary of findings.
- Do not invent error codes or resolution steps not present in [ERROR_CATALOG].

## EXAMPLES
[FEW_SHOT_EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

Generate the complete decision tree now.

To adapt this template, start by populating [ERROR_CATALOG] with your structured error data—typically a JSON array of objects containing code, http_status, message, and known_causes. Choose an [OUTPUT_FORMAT] such as JSON, YAML, or Mermaid.js for diagram rendering. The [FEW_SHOT_EXAMPLES] placeholder should contain one or two complete branches demonstrating the expected node structure and depth. Set [RISK_LEVEL] to low, medium, or high to control how aggressively the model requires confirmation gates. After generating the tree, validate coverage by scripting a check that every error code in your input catalog appears in at least one resolution leaf. For high-risk production environments, route the generated tree through a human review step before embedding it in a runbook or support tool.

The troubleshooting decision tree prompt is designed to be called programmatically from a support engineer's diagnostic console or an automated triage pipeline. It accepts a structured input payload containing the error code, observed symptoms, and system context, and returns a complete decision tree in a machine-readable format. The primary integration point is a backend service that receives an error event, enriches it with relevant telemetry, and invokes the LLM with this prompt to generate an interactive diagnostic path. This is not a chat interface; it is a batch generation call that produces a static tree which the frontend then renders as a step-by-step troubleshooting flow.

To wire this into an application, wrap the prompt in a function that constructs the [ERROR_CATALOG], [SYMPTOMS], and [SYSTEM_CONTEXT] placeholders from live data sources. The error catalog should be pulled from your API gateway's error registry or an OpenAPI spec parser. Symptoms should be extracted from log aggregators, APM traces, or user-reported descriptions. System context—such as service versions, region, and recent deployments—should come from your infrastructure metadata store. Before calling the model, validate that every error code in the input has at least one known resolution path in your runbook database; if not, flag it for human triage instead of generating a potentially hallucinated tree. After receiving the model output, run a structural validator that checks: (1) the JSON conforms to the expected schema with error_code, branches, and terminal_leaves keys; (2) every branch question has at least two answer options; (3) every leaf node contains a non-empty resolution_steps array; and (4) the tree depth does not exceed a configurable maximum to prevent infinite loops. If validation fails, retry once with the validation errors appended to the [CONSTRAINTS] field, then escalate to a human reviewer on the second failure.

For production deployment, use a model with strong structured output capabilities and low latency, such as Claude 3.5 Sonnet or GPT-4o with JSON mode enabled. Set temperature to 0 or a very low value to maximize determinism. Log every generated tree alongside the input context, validation results, and the support engineer's eventual resolution path to build a feedback corpus. This corpus enables periodic evaluation: sample 100 trees per week, have senior support engineers rate them on diagnostic accuracy and actionability, and track the percentage of trees where the engineer followed the generated path to successful resolution. If the success rate drops below a defined threshold, trigger a prompt review cycle. Avoid using this prompt for error codes classified as security-sensitive, where exposing diagnostic logic could aid an attacker; route those to a human-only queue. Finally, implement a feedback button in the diagnostic console that lets engineers flag incorrect branches or missing resolution steps, feeding that signal directly into your prompt improvement backlog.