Config-as-Code Documentation Prompt

This prompt is designed for platform engineers and DevOps teams who maintain configuration in version-controlled repositories (e.g., YAML, JSON, TOML, or HCL files). The primary job-to-be-done is to transform raw config-as-code files into structured, human-readable reference documentation that includes parameter hierarchies, default values, inheritance rules, and a PR review checklist. The ideal user is a senior engineer or technical lead who needs to ensure that the documentation stays synchronized with the live config source of truth without manual copy-paste drift.

Use this prompt when you have a stable config schema or a set of config files in a repository and you need to produce a Markdown reference page for internal or external consumers. The prompt requires you to provide the raw config file content as [CONFIG_SOURCE], any existing schema definitions as [SCHEMA_CONTEXT], and the target environment or audience as [DOCUMENTATION_CONTEXT]. It is most effective for configs with clear hierarchical structures, explicit default values, and comments that describe each parameter's purpose. The output will include a structured parameter table, a visual tree of the config hierarchy, documented inheritance and override rules, and a checklist for PR reviewers to verify that config changes are reflected in the documentation.

Do not use this prompt for highly dynamic configurations that are generated at runtime and have no static representation in a repository, or for configs where the source of truth is a live database or a UI-driven admin panel. This prompt is also not a substitute for a configuration validation engine; it documents what the config should look like, but it does not validate that a given config file is correct. For high-risk environments where incorrect documentation could lead to production outages, always pair the generated output with a human review step and a CI/CD check that diffs the generated docs against the config repo to detect drift.

This prompt template is designed to ingest a snapshot of a config-as-code repository—typically a directory of YAML, JSON, TOML, or HCL files—and produce a structured, human-readable reference document. It is built for platform engineers who need to keep documentation synchronized with the source of truth. The template uses square-bracket placeholders for all variable inputs, allowing you to inject the specific file tree, schema definitions, and documentation requirements for your project. Before using this prompt, ensure you have assembled the raw configuration files, any associated schema or validation rules, and a clear definition of the output structure you require.

textCopy
You are a technical documentation agent for a platform engineering team. Your task is to generate a comprehensive configuration reference document from a config-as-code repository.

## INPUT
[CONFIG_FILE_TREE]
[CONFIG_FILE_CONTENTS]

## CONTEXT
[SCHEMA_DEFINITIONS]
[INHERITANCE_RULES]
[DEPRECATION_POLICY]

## OUTPUT SCHEMA
Generate a Markdown document with the following sections:
1.  **File Structure Overview:** A tree diagram of the configuration directory.
2.  **Parameter Reference:** For each parameter, document:
    - **Name:** The full path (e.g., `parent.child.parameter`)
    - **Type:** The expected data type.
    - **Required:** Yes/No.
    - **Default:** The default value if not set.
    - **Description:** A concise explanation of the parameter's purpose.
    - **Valid Range/Options:** Any constraints, enums, or regex patterns.
    - **Deprecation:** Status and migration path, if applicable.
3.  **Inheritance and Override Rules:** Explain how values are merged from different files or scopes.
4.  **PR Review Checklist:** A checklist for reviewers to use when configuration changes are proposed.

## CONSTRAINTS
- Derive all information strictly from the provided [CONFIG_FILE_CONTENTS] and [SCHEMA_DEFINITIONS]. Do not invent parameters.
- If a parameter's description is missing from the source, mark it clearly as `[UNDOCUMENTED]`.
- For any parameter marked as deprecated, include the exact deprecation version and the replacement parameter name from [DEPRECATION_POLICY].
- The PR Review Checklist must include items for checking default value changes, new required parameters, and security implications.

## EXAMPLES
[FEW_SHOT_EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

To adapt this template, replace each bracketed placeholder with the relevant data for your repository. [CONFIG_FILE_TREE] should be the output of a command like tree, and [CONFIG_FILE_CONTENTS] should contain the full text of all configuration files. [SCHEMA_DEFINITIONS] can be your JSON Schema or cue definitions. The [FEW_SHOT_EXAMPLES] placeholder is critical for steering the output style; provide 1-3 examples of well-documented parameters from your existing docs. If the [RISK_LEVEL] is set to high, the prompt should be followed by a mandatory human review step before publication. For production use, wire this prompt into a CI/CD pipeline that triggers on merges to the config repository, ensuring documentation is regenerated and reviewed automatically.

This prompt is designed to be embedded in a documentation pipeline that triggers on changes to a version-controlled configuration repository. The ideal harness is a CI/CD job or a scheduled GitHub Action that detects diffs in config files (e.g., YAML, JSON Schema, or HCL), extracts the changed sections, and passes them to the prompt as [CONFIG_SOURCE]. The output should be treated as a draft that requires structural validation before it can be merged into the live documentation site. Do not wire this prompt directly to a public-facing docs endpoint without a review gate.

The implementation should follow a strict validate-then-merge pattern. After the model returns the generated Markdown reference, run a structural validator that checks for required sections: parameter hierarchy, inheritance rules, default values, and deprecation warnings. A simple JSON Schema or custom parser can verify that every config key in the source has a corresponding entry in the output. If validation fails, retry the prompt once with the validation errors appended to [CONSTRAINTS] as a correction hint. Log the full prompt, response, and validation result to an audit trail for debugging. For model choice, a capable mid-tier model like claude-3.5-sonnet or gpt-4o balances accuracy and cost; avoid smaller models that may drop required fields or hallucinate inheritance rules.

The most common production failure mode is drift between the config repo and the generated docs. To mitigate this, the harness should store a hash of the config source alongside the generated documentation artifact. On each run, compare the current source hash to the stored hash and skip generation if nothing changed. Additionally, implement a periodic full-scan job that re-generates all config docs and diffs them against the live versions, flagging any undocumented parameters for human review. Never auto-merge documentation that introduces new parameters without a corresponding PR review checklist item, as this can expose unreleased or insecure configuration surfaces to users before they are ready.