Exit Code Documentation Prompt Template

This prompt is for CLI maintainers and platform engineers who need to transform raw source code, help text, or internal error catalogs into a structured, user-facing exit code reference. The job-to-be-done is preventing undocumented failure states from reaching users. When a CLI exits with code 137, a user should not have to grep the repository to understand what happened. Use this prompt when you have access to the source code that defines exit points, error-handling logic, or a list of known error strings, and you need a consistent mapping of numeric codes to error categories, typical causes, stderr patterns, and actionable recovery steps. The ideal user is someone who owns the CLI's reliability surface and needs documentation that support engineers and end-users can actually follow.

Do not use this prompt when you lack access to the implementation. If you are documenting a third-party binary with no source code, no --help output, and no error catalog, the model will hallucinate plausible but incorrect exit codes. In that case, you must first run the binary under controlled failure conditions to capture real stderr output and exit codes, then feed those observations into the prompt as [CONTEXT]. Similarly, do not use this prompt for CLIs that do not follow the convention of meaningful exit codes—if every failure exits with code 1 and prints a stack trace, the prompt will produce a thin reference that adds little value. The prompt is also not a replacement for a troubleshooting guide; it documents what each code means, not a decision tree for diagnosing complex failures. For that, use the CLI Exit Code Troubleshooting Guide Prompt instead.

Before running this prompt, gather the required inputs: the source code paths that contain os.Exit, sys.exit, System.exit, or equivalent calls; any internal error-type enumerations; and representative stderr output for each failure mode. The prompt's harness should validate that every exit point found in source produces a documented entry, and that no documented code is unreachable. After generating the reference, wire it into your CI pipeline so that new exit codes introduced in pull requests trigger a documentation drift alert. This closes the loop between code changes and user-facing documentation, which is the core value of this playbook.

This prompt template is designed to produce a complete, structured exit code reference for a CLI tool. It maps every possible numeric exit code to its error category, typical causes, stderr patterns, and recommended user recovery actions. The template uses square-bracket placeholders that you must replace with your project-specific values before running. The goal is to create documentation that is directly usable by operators, support engineers, and automated monitoring systems.

textCopy
You are a technical writer specializing in CLI tool documentation. Your task is to generate a complete exit code reference for a command-line tool.

## Input
- Source code or binary path: [SOURCE_CODE_PATH_OR_BINARY]
- Help text output: [HELP_TEXT_OUTPUT]
- Existing documentation (if any): [EXISTING_DOCS]
- Target audience: [AUDIENCE] (e.g., SRE, end-user, support engineer)

## Constraints
- Document every exit code the tool can produce. Do not skip codes reserved by the OS or language runtime unless they are explicitly handled by the tool.
- For each exit code, provide: numeric code, symbolic name (if any), error category, typical causes, a representative stderr pattern, and a step-by-step recovery action for the user.
- If an exit code is undocumented in the source, flag it as "Undocumented in source" and infer its meaning from context.
- Use clear, imperative language for recovery actions.
- [ADDITIONAL_CONSTRAINTS]

## Output Schema
Return a JSON object with the following structure:
{
  "tool_name": "string",
  "version": "string",
  "exit_codes": [
    {
      "code": 0,
      "symbolic_name": "SUCCESS",
      "category": "Success",
      "description": "The command completed successfully.",
      "typical_causes": ["All operations finished without error."],
      "stderr_pattern": null,
      "recovery_steps": ["No action required."]
    },
    {
      "code": 1,
      "symbolic_name": "GENERAL_ERROR",
      "category": "Runtime Error",
      "description": "A general, non-specific error occurred.",
      "typical_causes": ["Invalid command syntax", "Missing required argument", "File not found"],
      "stderr_pattern": "error: .*",
      "recovery_steps": ["Check the command syntax using --help.", "Verify all required arguments are provided.", "Ensure input files exist and are readable."]
    }
  ],
  "undocumented_codes": [
    {
      "code": 130,
      "inferred_meaning": "Terminated by SIGINT (Ctrl+C)",
      "source_location": "Not explicitly handled; default OS behavior"
    }
  ]
}

## Examples
[FEW_SHOT_EXAMPLES]

## Risk Level
[RISK_LEVEL] (If 'high', require human review of all recovery steps before publication.)

To adapt this template, start by replacing [SOURCE_CODE_PATH_OR_BINARY] with a pointer to your codebase or a path to the compiled binary. Provide the raw output of your-cli-tool --help for [HELP_TEXT_OUTPUT]. Use [ADDITIONAL_CONSTRAINTS] to enforce style guide rules, such as "Recovery steps must not require root access" or "Do not document internal debug codes." The [FEW_SHOT_EXAMPLES] placeholder is critical for teaching the model the exact tone and level of detail you expect; include at least two well-crafted exit code entries as examples. After generation, always validate the output against the source code to catch missing or hallucinated codes before publishing.

The exit code documentation prompt is designed to run as part of a documentation build pipeline, not as a one-off manual query. The harness should invoke the prompt once per CLI binary or source tree, passing extracted exit code paths as [CODE_PATHS] and any existing documentation as [CURRENT_DOCS] for diff-aware updates. The model should receive the full list of code paths discovered by static analysis (e.g., grep for os.Exit, sys.exit, return codes in main functions) so it can flag undocumented exits rather than hallucinating coverage. Run this prompt after every release that changes error handling, and treat the output as a pull request against your docs repository.

Validation and retry logic is critical because exit code documentation errors mislead operators during incidents. After the model returns a structured exit code reference, run a coverage validator that parses the output table and compares numeric codes against the source-derived [CODE_PATHS] list. Flag any code present in source but missing from the documentation as a COVERAGE_GAP, and any code in the documentation but absent from source as a STALE_ENTRY. If coverage gaps exceed a threshold (e.g., >0 undocumented exit codes), trigger a retry with explicit feedback: append the missing codes to the prompt as [MISSING_CODES] and request a targeted update. For high-reliability CLIs, add a human review gate that requires a maintainer to approve any exit code whose recovery_action field recommends destructive operations (e.g., rm -rf, database resets, or credential rotation). Log every generation with the source commit SHA, the model version, the coverage percentage, and the reviewer identity for auditability.

Model choice and tool integration should favor models with strong structured output support (GPT-4o, Claude 3.5 Sonnet, or equivalent) and JSON mode enabled. The prompt expects a schema with fields like code, category, cause, stderr_pattern, and recovery_action—enforce this with your model's structured output API rather than hoping the model follows a markdown table. Wire the harness into your existing docs toolchain: if you use a static site generator, the output should render as a dedicated exit codes page with anchor links; if you ship man pages, post-process the output into the EXIT STATUS section. Avoid running this prompt on every commit—trigger it on release tags or when grep detects changes to exit-relevant code paths. The harness should also compare generated stderr_pattern fields against actual error output from integration tests to catch drift between documented and real error messages.