CLI Error Message Catalog Generation Prompt

This prompt is designed for support engineers, CLI maintainers, and platform teams who need to build a structured, searchable catalog of every error message a command-line tool can emit. The primary job-to-be-done is transforming raw error strings, source code, and help text into a machine-readable reference that maps each error to its root cause, affected flags, related exit codes, and actionable resolution steps. The ideal user is someone who owns the support or documentation experience for a CLI tool and needs to ensure that every possible failure mode is documented, discoverable, and linked to a clear remediation path.

Use this prompt when you have access to the CLI's source code, can run the binary to trigger error states, or have a comprehensive list of error strings from logs. The prompt expects a [CONTEXT] that includes the raw error text, relevant source code snippets, and any existing documentation. It is most effective for CLIs with a finite, enumerable set of error messages—typically those that use explicit error codes, structured error types, or well-defined exit code conventions. The output is a structured catalog entry, not a narrative troubleshooting guide; it is meant to be ingested by a support knowledge base, a --explain-error command, or an internal troubleshooting tool.

Do not use this prompt for generating user-facing troubleshooting prose directly. It is not designed to write tutorials, FAQs, or conversational support scripts. Avoid using it when the CLI's error messages are dynamically generated from external services, as the catalog will quickly become stale without a live integration. This prompt is also a poor fit for CLIs that produce vague, unstructured error output without distinct error identifiers—in those cases, the source code itself must be improved before a meaningful catalog can be generated. Finally, if the goal is to fix the errors rather than document them, this is the wrong tool; pair this catalog with a separate prompt for error message improvement.

Before running this prompt, ensure you have a complete inventory of error strings. A common failure mode is feeding the prompt an incomplete list, which produces a catalog with dangerous gaps. After generation, you must validate the catalog by cross-referencing it against error strings extracted directly from the source code. The companion evaluation harness should flag any error message found in the source that is missing from the catalog, and it should test a sample of resolution steps against a live CLI environment to confirm they actually resolve the error. Human review is required for any resolution step that involves destructive actions, such as data cleanup commands or configuration resets.

This prompt template is the core instruction set for generating a structured, searchable catalog of every error message a CLI tool can emit. It is designed to be copied directly into your AI harness, with placeholders that you replace with your specific CLI's source code, documentation, and output constraints. The template forces the model to map error strings to their root causes, affected flags, resolution steps, and related exit codes, producing a machine-readable output that can be ingested by a support knowledge base or a diagnostic tool.

textCopy
You are an expert CLI support engineer and technical writer. Your task is to generate a complete, structured error message catalog for a command-line interface tool.

Analyze the provided [SOURCE_CODE] and [HELP_TEXT_OUTPUT] to identify every possible error message the CLI can emit. For each unique error message, produce a structured record that includes the error string, its root cause, the affected flags or subcommands, a clear resolution step, and the associated exit code.

[CONSTRAINTS]
- Do not invent error messages. Only catalog messages that are explicitly defined in the provided source code or help text.
- If an error message is constructed dynamically with variables, represent the variable part with a placeholder like <variable_name>.
- For each error, the resolution step must be a single, actionable instruction that a user can execute.
- Group related errors by the component or subcommand that triggers them.

[OUTPUT_SCHEMA]
Return a single JSON object with a key "error_catalog" containing an array of error objects. Each object must have the following fields:
- "error_id": A unique slug for the error (e.g., "auth_token_expired").
- "error_pattern": The exact error string or a regex pattern if the message is dynamic.
- "exit_code": The integer exit code associated with this error.
- "component": The subcommand, flag, or module that triggers this error.
- "root_cause": A concise explanation of why this error occurs.
- "affected_flags": An array of flag names (long form, e.g., ["--token", "--profile"]) that are relevant to this error.
- "resolution_step": A single, direct instruction for the user to resolve the error.
- "related_errors": An array of error_id strings for other errors that commonly occur alongside or as a result of this one.

[EXAMPLES]
Input Source Code Snippet:
if token == "" {
    return fmt.Errorf("authentication failed: token is empty")
}

Output Record:
{
  "error_id": "auth_token_empty",
  "error_pattern": "authentication failed: token is empty",
  "exit_code": 1,
  "component": "auth",
  "root_cause": "The --token flag was not provided or was set to an empty string.",
  "affected_flags": ["--token"],
  "resolution_step": "Run 'cli-tool login' to generate a new token, or set the --token flag with a valid value.",
  "related_errors": ["auth_token_expired", "auth_insufficient_scopes"]
}

[RISK_LEVEL]
This output will be used to build a customer-facing troubleshooting guide. Inaccurate resolution steps can lead to user frustration and data loss. All resolution steps must be validated against the source code logic before publication.

To adapt this template, replace the [SOURCE_CODE] and [HELP_TEXT_OUTPUT] placeholders with the actual files or text dumps from your CLI project. If your CLI is written in a language other than Go, adjust the example in the prompt to match your language's error-raising syntax to improve model accuracy. The [OUTPUT_SCHEMA] is a strong constraint, but you should modify the field definitions to match your internal support taxonomy. Before integrating this prompt into a production pipeline, implement a validation step that parses the JSON output and checks for missing exit codes or error patterns that exist in the source but are absent from the catalog. This prompt is not a substitute for a human review of resolution steps, especially for errors that can cause data loss or irreversible state changes.

This prompt is designed to be one step in a documentation generation pipeline, not a standalone chat interaction. The primary input is a raw extraction of error-producing code paths from your CLI source, typically gathered by a static analysis script that identifies fmt.Errorf, log.Fatal, return err, or equivalent patterns in your language. The prompt's job is to transform that raw list into a structured, searchable catalog. The output should be a JSON array of error objects, each containing the error string, cause, affected flags, resolution steps, and exit code. This structured output is then ingested by your documentation site generator, support knowledge base, or a CLI --explain-error lookup tool.

Validation and Grounding: The most critical failure mode is an error message existing in the source code but missing from the generated catalog. To prevent this, the harness must perform a completeness check: count the number of error-producing statements in the source extraction and compare it to the number of entries in the model's output. A second validation pass should use a separate LLM call or a deterministic script to verify that each resolution step references real commands or configuration options that exist in the current CLI version. For high-reliability environments, implement a human-in-the-loop review queue that flags any error message with a severity of CRITICAL or FATAL for manual approval before the catalog is published.

Model Choice and Retries: Use a model with strong JSON mode and large context windows, such as claude-sonnet-4-20250514 or gpt-4o, as the source extraction can be lengthy. Implement a retry strategy with exponential backoff for schema validation failures. If the initial output fails JSON schema validation, feed the raw output and the validation errors back into the model with a repair prompt. Log every generation attempt, including the prompt template version, model used, and validation pass/fail status, to create an audit trail. Avoid using this prompt for real-time error explanation in a live CLI session; instead, pre-generate the catalog and serve it from a static file or database for low-latency lookups.