Config Change Changelog Generator Prompt

This prompt is designed for release managers and platform engineers who need to convert a stream of config-related commits, pull requests, and issue tracker entries into a structured, categorized changelog. The goal is to produce a document that clearly separates added, changed, deprecated, and removed configuration parameters, with enough context for downstream consumers to understand the impact. Use this prompt when you have a collection of raw change entries and need a consistent, reviewable changelog draft.

The prompt assumes that the input commits are already filtered to config-related changes; feeding it unfiltered commit logs will produce noisy, unreliable output. Do not use this prompt for generating narrative release announcements, marketing-facing release notes, or changelogs for non-config changes such as application code features. The ideal input is a curated list of commit messages, PR descriptions, or issue titles that specifically touch configuration files, environment variables, feature flags, or infrastructure-as-code parameters.

Before using this prompt, ensure you have a reliable mechanism to isolate config-only changes from your broader change history. Common approaches include filtering by file path patterns (e.g., *.yaml, *.toml, .env.example, values.yaml), commit message conventions (e.g., config: prefix), or issue labels (e.g., area/config). The prompt works best when each input entry contains the parameter name, the change type, and a brief rationale—if your raw data lacks this detail, consider a pre-processing step to enrich entries before feeding them to this generator.

This template converts raw config-related commits, pull request descriptions, and issue references into a structured, categorized changelog. It is designed to be wired into a release automation pipeline where the input is a batch of changes from a version control system. The prompt enforces a strict output schema so that downstream tooling—such as release note generators, documentation sites, or compliance auditors—can consume the changelog without manual reformatting.

textCopy
You are a release changelog generator for configuration changes. Your task is to analyze the provided list of commits and pull requests, identify only those that modify configuration parameters, environment variables, feature flags, or config schema files, and produce a structured changelog in the exact JSON format specified below.

## INPUT
[CHANGE_LOG_INPUT]

## OUTPUT SCHEMA
Return a single JSON object with the following structure. Do not include any text outside the JSON object.

{
  "release_version": "string (the version or tag this changelog applies to)",
  "generated_at": "string (ISO 8601 timestamp of generation)",
  "categories": {
    "added": [
      {
        "parameter_name": "string (the config key or variable name)",
        "type": "string (one of: environment_variable, config_file_key, feature_flag, cli_argument, helm_value, terraform_variable)",
        "description": "string (one-sentence description of the new parameter)",
        "default_value": "string or null",
        "required": true or false,
        "source_commits": ["string (commit SHA)"],
        "source_prs": ["string (PR number or URL)"]
      }
    ],
    "changed": [
      {
        "parameter_name": "string",
        "change_type": "string (one of: default_updated, validation_rule_changed, type_changed, range_updated, behavior_modified)",
        "previous_behavior": "string (what the parameter did before)",
        "new_behavior": "string (what the parameter does now)",
        "breaking": true or false,
        "migration_required": true or false,
        "source_commits": ["string"],
        "source_prs": ["string"]
      }
    ],
    "deprecated": [
      {
        "parameter_name": "string",
        "deprecation_date": "string (ISO 8601 date)",
        "sunset_date": "string (ISO 8601 date or null if not yet set)",
        "replacement_parameter": "string or null (the parameter that replaces this one)",
        "migration_instructions": "string (brief guidance for users)",
        "source_commits": ["string"],
        "source_prs": ["string"]
      }
    ],
    "removed": [
      {
        "parameter_name": "string",
        "removal_date": "string (ISO 8601 date)",
        "last_version_supported": "string (the last release that supported this parameter)",
        "reason": "string (why it was removed)",
        "source_commits": ["string"],
        "source_prs": ["string"]
      }
    ]
  },
  "non_config_changes_skipped": ["string (list of commit SHAs or PRs that were reviewed but contained no config changes)"],
  "uncertain_entries": [
    {
      "commit_or_pr": "string",
      "reason": "string (why the classifier was uncertain)",
      "suggested_category": "string (best guess: added, changed, deprecated, removed)"
    }
  ]
}

## CONSTRAINTS
- Only include changes that directly affect configuration parameters, environment variables, feature flags, or config schemas.
- Do not include code-only changes, documentation typos, test fixtures, or logging changes unless they modify a config parameter's behavior.
- If a commit touches both config and non-config files, extract only the config-relevant portion.
- If you cannot determine the category with high confidence, place the entry in `uncertain_entries` with a reason.
- Every entry must include at least one source commit or PR reference.
- Breaking changes must be flagged explicitly.
- If no config changes are found, return an object with empty category arrays and populate `non_config_changes_skipped`.

## EXAMPLES
[FEW_SHOT_EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

To adapt this template, replace [CHANGE_LOG_INPUT] with a structured dump of commits and PR descriptions—ideally pre-filtered to the release window. The [FEW_SHOT_EXAMPLES] placeholder should contain 2–3 annotated examples showing correct categorization, especially for ambiguous cases like a default value change that is also a breaking change. Set [RISK_LEVEL] to high when the changelog feeds compliance artifacts or customer-facing release notes; this should trigger downstream human review of the uncertain_entries list before publication. For low-risk internal changelogs, you can set [RISK_LEVEL] to low and auto-publish with a confidence threshold check on uncertain entries.

This prompt is designed to run as a step in a release automation pipeline, not as a one-off chat interaction. The primary input is a structured diff of configuration-related commits and PRs, typically extracted from your version control system. Before calling the model, assemble the [CONFIG_DIFF] input by filtering commits that touch config schemas, .env files, Helm values, Terraform variables, or feature flag definitions. Each entry should include the commit message, changed files, and a link to the full diff or PR. This pre-processing step is critical—feeding the model unfiltered commit logs will produce noisy, miscategorized changelogs.

Wire the prompt into your CI/CD system (GitHub Actions, GitLab CI, Jenkins) as a post-merge or pre-release job. The job should: (1) extract config-related changes using git log with path filters, (2) assemble the [CONFIG_DIFF] payload, (3) call the LLM with the prompt template and a strict JSON output schema, (4) validate the returned JSON against your expected schema, and (5) write the validated output to a CHANGELOG.md or release notes artifact. Use a model that supports structured output guarantees (GPT-4o with response_format, Claude with tool use, or any model with a JSON mode). Set temperature=0 to maximize categorization consistency across runs. Implement a retry loop: if the output fails JSON schema validation, retry up to 2 times with the validation errors appended to the prompt as feedback. After 3 failed attempts, flag the run for human review and attach the raw diff and partial output to a ticket.

The output schema must enforce the four required categories: added, changed, deprecated, and removed. Each entry requires parameter_name, description, migration_notes (nullable), and pr_link. Validate that every entry in the model's output maps back to at least one commit in the input diff—entries without a matching source commit are hallucinations and must be stripped before publication. Log a warning count of stripped entries for observability. For high-risk config changes (deprecations, removals, security-sensitive defaults), add a human approval gate: the pipeline should post the generated changelog as a PR comment and require a maintainer to check a box before the release proceeds. This is not optional for production infrastructure configs.

For evaluation, maintain a golden dataset of 20–30 known config changes with expected categorization. Run the prompt against this dataset on every prompt change and assert that categorization accuracy stays above 95% and that no entries are invented. Track two failure modes specifically: (1) missing entries—config changes that appear in the diff but not in the output, and (2) incorrect categorization—a deprecation labeled as a change, or an addition labeled as a removal. Both are regressions that block prompt updates. Store the eval results alongside the prompt version in your prompt registry so you can trace accuracy degradation to specific prompt edits.

Do not use this prompt for real-time or user-facing changelog generation without the validation and approval harness described above. The model can miscategorize breaking changes as minor, omit security-sensitive deprecations, or hallucinate parameter names that look plausible but don't exist in your codebase. The harness is the safety layer—the prompt alone is not enough for production release workflows.