CLI Exit Code Troubleshooting Guide Prompt

This prompt is designed for support engineers and CLI tool maintainers who need to build a decision-tree troubleshooting guide that maps exit codes and error patterns to diagnostic steps and resolutions. The ideal user has access to a catalog of known exit codes, error messages, and a test environment where they can intentionally trigger error conditions to validate each diagnostic path. The core job-to-be-done is transforming a flat list of error codes into a structured, actionable guide that walks an end user from an error symptom through a series of diagnostic commands to a verified resolution, reducing mean time to recovery for CLI users.

Use this prompt when you have a stable CLI tool with documented or discoverable exit codes and the ability to execute diagnostic commands against a live test harness. The prompt expects you to provide a mapping of exit codes to error patterns, typical stderr output, and the diagnostic commands that can confirm the root cause. The output is a decision-tree guide, not a simple reference table; each branch should lead to a specific resolution step. Do not use this prompt when you lack access to the CLI tool for live testing, when exit codes are not documented or discoverable, or when the troubleshooting requires deep system-level state that cannot be reproduced in a test harness. In those cases, a static error code reference or a manual runbook is more appropriate.

Before using this prompt, gather your raw materials: a complete list of exit codes, example error messages for each, the diagnostic commands that reveal the underlying state, and the resolution commands that fix the issue. The prompt works best when you can validate each diagnostic path against intentionally triggered error conditions. After generating the guide, run a harness that executes each diagnostic command against a known-bad state and confirms that the resolution step restores the system to a working condition. If any path fails validation, iterate on the prompt with more specific error patterns or additional diagnostic steps. Avoid shipping the guide without end-to-end validation of at least the most common error paths.

This prompt template is designed to be dropped directly into your AI harness or prompt management system. It instructs the model to act as a senior support engineer and produce a structured troubleshooting guide. The template uses square-bracket placeholders for all dynamic inputs—exit code catalogs, error message lists, diagnostic commands, and output format preferences—so you can populate it programmatically from your CLI's source of truth before each generation run.

codeCopy
You are a senior support engineer writing a troubleshooting guide for the [CLI_TOOL_NAME] CLI tool. Your task is to produce a decision-tree guide that maps exit codes and error patterns to diagnostic steps and resolutions.

## Exit Code Reference
[EXIT_CODE_CATALOG]

## Error Message Catalog
[ERROR_MESSAGE_CATALOG]

## Diagnostic Commands Available
[DIAGNOSTIC_COMMANDS]

## Output Requirements
Produce a troubleshooting guide in the following structure:

1. **Symptom Recognition**: For each exit code, describe the user-visible symptoms, including typical stderr output patterns and the context in which the error occurs.

2. **Decision Tree**: Create a branching decision tree that starts with the exit code or error message and guides the user through diagnostic steps. Each node must include:
   - The diagnostic command to run
   - The expected output for a healthy state
   - The output patterns that indicate specific failure modes
   - The next step based on each possible outcome

3. **Resolution Steps**: For each leaf node in the decision tree, provide:
   - The exact commands to run to resolve the issue
   - Verification steps to confirm the resolution worked
   - Rollback or cleanup commands if the resolution fails

4. **Escalation Criteria**: Define when the user should stop self-troubleshooting and escalate to a support engineer, including the exact information to include in the escalation ticket.

## Constraints
- Every diagnostic command must be safe to run in a user environment (no destructive operations without explicit warnings).
- Every resolution step must include a verification command.
- The decision tree must cover every exit code in the provided catalog.
- Use [OUTPUT_FORMAT] for the final guide.
- Flag any exit code or error message that lacks a known resolution with `[UNRESOLVED]` and suggest escalation.

To adapt this template for your own CLI tool, replace the bracketed placeholders with structured data extracted from your build pipeline or source code. [EXIT_CODE_CATALOG] should contain a list of numeric codes, their meanings, and associated error categories. [ERROR_MESSAGE_CATALOG] should map exact error strings to their likely causes. [DIAGNOSTIC_COMMANDS] must be a curated list of safe, read-only commands users can run to inspect state. The [OUTPUT_FORMAT] placeholder lets you specify whether the final guide should be Markdown, HTML, or a structured JSON object for rendering in a support portal. Always validate the generated guide against a golden set of intentionally triggered error conditions before publishing.

The CLI Exit Code Troubleshooting Guide Prompt is designed to be wired into a documentation generation pipeline with automated validation. The harness must test each diagnostic path against intentionally triggered error conditions to verify that the resolution steps actually resolve the issue. This is not a prompt you run once and publish—it is a prompt you integrate into a CI-like pipeline where every generated decision tree is exercised against a live or containerized CLI environment before it reaches users.

The harness architecture has four layers. First, an Error Injection Layer uses a test environment where each exit code can be reliably triggered—this may involve setting incorrect permissions, providing invalid configs, disconnecting network interfaces, or using fault-injection tools like strace wrappers or filesystem mocks. Second, a Diagnostic Execution Engine walks each path in the generated decision tree, executes the diagnostic commands against the error state, and verifies that the output matches the expected patterns described in the guide. Third, a Resolution Validator follows the resolution steps and confirms the exit code returns to 0 and the tool operates correctly; if a resolution fails, the path is flagged for human review. Fourth, a Completeness Checker compares the exit codes covered in the generated guide against the source-of-truth exit code catalog and flags any exit code that lacks a documented troubleshooting path.

Retry and repair logic is essential. If the model output fails validation—missing exit codes, unresolvable paths, unsafe commands—retry the prompt with the specific failure feedback appended as additional context. After 3 retries, escalate the unresolved paths to a human technical writer rather than looping indefinitely. Log every generated diagnostic path, the harness test result, and any discrepancies between expected and actual command behavior. This log becomes the audit trail for the troubleshooting guide's accuracy and is invaluable when the CLI itself changes and the guide needs updating.

For model choice, prefer a model with strong instruction-following and structured output capabilities. The prompt should be called with a low temperature (0.1–0.3) to maximize consistency across diagnostic paths. If your CLI has more than 20 exit codes, consider splitting the prompt into multiple calls grouped by error category—permission errors, network errors, input validation errors—to keep each generation focused and testable. Always run the harness in an isolated environment; never execute diagnostic commands from an untested guide against production systems.