CLI Pipe and Redirection Behavior Prompt

This prompt is designed for CLI tool maintainers and platform engineers who need to document how a command behaves as a composable unit inside Unix pipelines. The core job-to-be-done is producing per-command documentation that explains stdin/stdout contracts, exit code propagation, signal handling, buffering behavior, and common pipeline patterns. It is not a general-purpose command reference generator. You should use this prompt when you already have flag documentation, subcommand trees, and basic usage examples, but you need to explain to users how the command composes with other tools, what happens when input is empty or a pipe breaks, and how to handle errors in a pipeline.

The ideal user is an engineer who understands process composition and needs to communicate data flow contracts to other developers. The prompt requires specific inputs: the command's help text or source annotations, known exit codes, and any existing documentation about input/output formats. It produces structured documentation covering the command's behavior as a pipeline component, including whether it reads from stdin by default or requires explicit flags, whether it buffers output or streams line-by-line, how it propagates or masks child process exit codes, and which signals it handles or forwards. The output should include concrete pipeline examples that demonstrate composition with common tools like grep, jq, xargs, and awk.

Do not use this prompt for generating initial flag references, subcommand trees, or installation guides. Those are separate documentation concerns covered by other prompts in the CLI documentation family. This prompt also assumes the command's basic behavior is stable and documented; it is not suitable for reverse-engineering undocumented binaries or for commands that do not participate in standard Unix pipelines. Before using this prompt, ensure you have validated the command's actual pipeline behavior through testing, as the prompt's output must be verified against real execution traces. If the command exhibits non-standard buffering, requires a TTY, or has complex signal handling, you should supplement the prompt's output with empirical test results.

This prompt template generates structured documentation for how a specific CLI command behaves in pipelines. It forces the model to reason about stdin/stdout contracts, buffering behavior, exit code propagation, and signal handling—details that are often omitted from standard command references but are critical for engineers composing reliable shell pipelines. Copy the template below, replace the square-bracket placeholders with your command's specifics, and run it against your chosen model.

textCopy
You are a technical writer documenting CLI pipeline behavior for the command [COMMAND_NAME] version [VERSION].

Your task is to produce a Pipeline Behavior Reference section that explains how this command interacts with pipes, redirects, and process composition.

## Required Inputs
- Command help text or source annotations: [HELP_TEXT_OR_SOURCE]
- Known exit codes and their meanings: [EXIT_CODES]
- Output format documentation (if applicable): [OUTPUT_FORMATS]

## Output Schema
Return a JSON object with the following structure:
{
  "command": "string",
  "stdin_contract": {
    "expects_input": "boolean",
    "input_type": "text | binary | json | csv | none",
    "encoding": "string (e.g., UTF-8, raw bytes)",
    "tty_vs_pipe_behavior": "string describing differences between interactive terminal input and piped input",
    "empty_input_behavior": "string describing what happens when stdin is empty or /dev/null",
    "buffering_notes": "string describing line-buffered vs block-buffered vs unbuffered behavior"
  },
  "stdout_contract": {
    "output_type": "text | binary | json | csv | mixed",
    "encoding": "string",
    "tty_vs_pipe_behavior": "string describing differences between terminal output and piped output (e.g., color stripping, formatting changes)",
    "is_reproducible": "boolean (does the same input always produce byte-identical output?)",
    "partial_output_on_failure": "string describing what, if anything, is written to stdout before a non-zero exit"
  },
  "stderr_contract": {
    "contains_diagnostics": "boolean",
    "contains_progress": "boolean",
    "contains_errors_only": "boolean",
    "machine_parseable": "boolean"
  },
  "exit_code_propagation": {
    "exit_codes": [
      {
        "code": "integer",
        "meaning": "string",
        "propagates_from_subprocess": "boolean",
        "recoverable": "boolean"
      }
    ],
    "pipefail_behavior": "string describing behavior under set -o pipefail",
    "signal_handling": {
      "sigpipe": "string describing behavior when downstream pipe closes",
      "sigint": "string describing interrupt behavior",
      "sigterm": "string describing termination behavior"
    }
  },
  "pipeline_patterns": [
    {
      "pattern": "string (a realistic pipeline example)",
      "description": "string explaining what the pattern does",
      "expected_behavior": "string describing expected stdout, stderr, and exit code",
      "caveats": "string listing any gotchas or edge cases"
    }
  ],
  "composability_notes": "string summarizing how this command composes with others, including known incompatibilities"
}

## Constraints
- Only document behavior you can verify from the provided help text or source annotations. If a behavior is undocumented, mark it as "unknown" rather than guessing.
- For each pipeline pattern, ensure the example is syntactically correct and uses realistic file names or inputs.
- Flag any behavior that differs between platforms (Linux, macOS, Windows) if evidence exists in the provided material.
- Do not invent exit codes or signal behaviors not present in the source material.

## Examples
[EXAMPLES]

## Risk Level
[RISK_LEVEL]

Adaptation notes: Replace [COMMAND_NAME] and [VERSION] with the specific command and release version. Populate [HELP_TEXT_OR_SOURCE] with the raw --help output, man page content, or relevant source code annotations. Fill [EXIT_CODES] with a structured list of known exit codes from your exit code documentation prompt. Use [OUTPUT_FORMATS] to describe any structured output modes (JSON, CSV, table). The [EXAMPLES] placeholder should contain 2-3 few-shot examples of correctly filled schemas for similar commands to guide output shape. Set [RISK_LEVEL] to low, medium, or high based on whether incorrect pipeline documentation could cause data loss, silent failures, or production incidents. For high-risk commands, add a human review step before publishing the generated documentation.

This prompt is designed to be called programmatically as part of a CLI documentation build step. The typical harness reads a command's --help output, its source annotations, or a structured command spec, then passes that data into the prompt as [COMMAND_SPEC] and [BEHAVIOR_EVIDENCE]. The model returns a structured pipeline behavior document that your system can render into Markdown, man pages, or a web reference. Because pipeline behavior documentation describes how commands compose, the harness must validate that every documented stdin/stdout contract, exit code propagation rule, and buffering note is internally consistent before publication.

Wire the prompt into a documentation pipeline that runs per-command. For each command, assemble the input context from: (1) the command's --help output or a parsed flag schema, (2) any source-level annotations about pipe behavior, signal handling, or TTY detection, and (3) a list of sibling commands that commonly appear in pipelines with this command. Pass these into [COMMAND_SPEC] and [BEHAVIOR_EVIDENCE] respectively. After the model returns its output, run a structured validation step: parse the documented stdin/stdout contracts and check that every claimed exit code appears in the command's actual exit code catalog. Flag any pipeline example that references a flag not present in the command's flag schema. For high-risk commands that modify filesystems or network state, add a human review gate before publication—an engineer should confirm that buffering behavior notes (line-buffered vs. block-buffered) match actual implementation, since incorrect buffering documentation causes the hardest-to-debug pipeline failures.

For retry logic, if the model output fails schema validation (missing required sections like stdin_contract, stdout_contract, pipeline_examples, or buffering_behavior), retry once with the validation errors appended to [CONSTRAINTS]. If the retry also fails, route the command to a manual documentation queue. Log every generation attempt with the command name, model version, validation pass/fail status, and whether human review was required. Avoid shipping pipeline documentation that claims a command "propagates all exit codes" unless you have tested that claim against actual set -o pipefail and PIPESTATUS behavior in your target shells.