Command Reference Page Assembly Prompt

This prompt is designed for technical writers and CLI maintainers who need to produce a single, internally consistent command reference page from multiple source artifacts. The ideal scenario is when you have raw --help output, source code annotations, hand-written usage examples, a table of exit codes, and configuration documentation that all describe the same command. Instead of manually reconciling these sources, you feed them into the prompt to generate a unified page containing a synopsis, description, options table, examples, exit codes, and see-also links. The core job-to-be-done is documentation assembly and consistency enforcement, not original research or behavior discovery.

Use this prompt when you have at least two distinct source artifacts for a command and need a structured reference page that passes documentation QA. The prompt excels at spotting contradictions between sources—for example, when the --help text lists a default value that differs from the source code annotation, or when an example uses a flag that is not documented in the options table. It also enforces structural completeness by checking that every required section (synopsis, description, options, examples, exit codes, see-also) is populated and that cross-references between sections are valid. The harness should validate the output against a schema that requires these sections and flag any missing or empty ones before the page is published.

Do not use this prompt when the command behavior is still in flux and cannot be verified against a live binary. The prompt assembles and reconciles existing documentation; it does not reverse-engineer behavior from an unstable codebase. Similarly, avoid this prompt when you lack source material entirely—if you have no help text, no source annotations, and no examples, the model will hallucinate plausible but incorrect command behavior. For high-risk or security-sensitive commands, always include a human review step where a subject-matter expert verifies the assembled page against the actual binary before publication. The next step after reading this section is to gather your source artifacts and prepare them as structured inputs for the prompt template.

This prompt template is designed to be the core instruction set you send to a model. It accepts structured inputs—help text, source annotations, usage examples, and exit code documentation—and produces a complete, internally consistent command reference page. The template uses square-bracket placeholders that you must replace with actual content before execution. Do not send the placeholders to the model; they represent the data injection points your application or manual workflow must fill.

textCopy
You are a technical writer assembling a complete command reference page for a CLI tool.
Your task is to synthesize the provided source artifacts into a single, unified reference document.

## Required Output Sections
Generate a command reference page with the following sections, in this order:
1.  **Synopsis**: A one-line usage summary showing the command structure.
2.  **Description**: A concise paragraph explaining the command's purpose.
3.  **Options**: A markdown table of all flags and options. Columns: `Flag`, `Type`, `Default`, `Description`.
4.  **Subcommands**: A list of subcommands with brief descriptions, if any exist.
5.  **Examples**: Realistic, annotated shell examples demonstrating common and edge-case usage.
6.  **Exit Codes**: A markdown table of exit codes. Columns: `Code`, `Description`, `Recovery`.
7.  **See Also**: A list of related commands or documentation links.

## Source Artifacts
- **Help Text**:
[HELP_TEXT]

- **Source Code Annotations**:
[SOURCE_ANNOTATIONS]

- **Usage Examples**:
[USAGE_EXAMPLES]

- **Exit Code Documentation**:
[EXIT_CODE_DOCS]

## Constraints
- [CONSTRAINTS]
- If any section cannot be populated from the provided sources, output the section heading and the text `*No information available from provided sources.*`.
- Ensure all flags in the help text appear in the Options table.
- Ensure all exit codes in the documentation appear in the Exit Codes table.
- Do not invent flags, examples, or exit codes not present in the source artifacts.

To adapt this template, replace each [PLACEHOLDER] with the corresponding text from your sources. The [CONSTRAINTS] placeholder is critical for enforcing style guides, specific formatting rules, or domain-specific requirements (e.g., 'All examples must use long-form flags,' or 'Sort options alphabetically'). After assembly, the harness should validate the output against the original source artifacts to ensure no information was dropped or hallucinated. For high-stakes documentation, always include a human review step before publication.

This prompt is designed to be the final assembly step in a multi-source documentation pipeline, not a standalone generator. Before calling this prompt, you should have already extracted structured data from help text, source annotations, and exit code documentation using the sibling extraction prompts in this pillar. The assembly prompt expects pre-processed, structured inputs in the [SECTIONS] placeholder—passing raw, unparsed help text will produce inconsistent results. The ideal implementation fetches these structured inputs from a documentation database or content API, assembles them into the prompt's expected schema, and then calls the model to produce the unified reference page.

Wire this prompt into a documentation CI/CD pipeline with explicit validation and retry logic. After the model returns the assembled reference page, run a validation harness that checks for: (1) internal consistency—do the options listed in the synopsis match the options table? (2) section completeness—are all required sections (synopsis, description, options, examples, exit codes, see-also) present and non-empty? (3) cross-reference integrity—do see-also links point to existing pages? (4) example accuracy—can the documented command examples be parsed without syntax errors? Use a structured output format (JSON with markdown content fields) so the validation harness can programmatically inspect each section. If validation fails, feed the specific failure messages back into a retry call with the original inputs plus a [CORRECTIONS] field containing the validator output. Limit retries to 2 attempts before flagging for human review.

For model choice, prefer models with strong instruction-following and long-context handling (GPT-4o, Claude 3.5 Sonnet, or equivalent). The prompt's output is primarily markdown, so strict JSON mode is not required, but you should wrap the output in a predictable container (e.g., a JSON object with sections as keys) to simplify downstream rendering. Implement logging that captures: the input sources used, the model and version, the raw output, validation results, and any human review decisions. This audit trail is essential when debugging why a specific command reference page has a stale flag or missing exit code. For high-risk CLI tools (security, infrastructure, compliance), always require a human review gate before publishing—the model can assemble, but a subject-matter expert must confirm that no dangerous flags are misdocumented or omitted.

Avoid wiring this prompt directly to a public-facing documentation site without validation. The most common production failure mode is stale cross-references: the model confidently links to a see-also page that was renamed or deleted. Mitigate this by maintaining a sitemap or page registry that the validation harness checks against. Another failure mode is example drift, where the assembled examples reference flags that were deprecated between extraction and assembly. If your pipeline caches extracted flag data, set a TTL that aligns with your CLI release cadence and invalidate caches on new version tags. Finally, do not use this prompt for commands with more than ~50 flags or deeply nested subcommand trees exceeding 10 levels—the context window will strain, and the model will start dropping sections. For those cases, split the assembly into per-subcommand pages and use a separate index-generation prompt.