Config Decision Record Prompt

Platform architects and DevOps engineers use this prompt to document why specific default values, constraints, or design choices were made for configuration parameters. The prompt produces ADR-style entries with context, alternatives considered, decision rationale, and consequences. Use this when you need to capture the reasoning behind a config decision for future maintainers, compliance auditors, or onboarding engineers. The output is a structured decision record that explains not just what the parameter is, but why it exists in its current form—critical context that source code comments and schema definitions rarely capture.

This prompt assumes you already know the parameter and its chosen value, and you need to document the why. You must supply the parameter name, its current value, the system context where it operates, and any alternatives that were evaluated. The prompt works best when you have a specific decision in mind—such as choosing a 30-second timeout over 10 seconds, or selecting AES-256-GCM over AES-128-CBC—and need to produce a durable record of that reasoning. Do not use this prompt for generating the config schema itself, extracting environment variables from code, or writing migration guides. Those tasks require different prompts in this pillar, such as the Config Schema to Markdown Table prompt or the Config Migration Guide Generator.

Before using this prompt, gather the decision context: what problem the parameter solves, which alternatives were seriously considered, what constraints influenced the choice (performance, security, cost, compatibility), and what consequences the decision creates for operators and downstream systems. The prompt will structure this into a consistent ADR format, but it cannot invent the reasoning—it can only organize and articulate what you provide. For high-risk configuration decisions affecting security posture, data durability, or compliance controls, always have a senior engineer review the generated decision record before it enters your documentation repository. The record becomes institutional memory that future incident responders and auditors will rely on.

This prompt template produces a structured Config Decision Record (CDR) that documents why a specific default value, constraint, or design choice was made for a configuration parameter. It follows an ADR-inspired format that captures context, alternatives considered, decision rationale, and consequences. Use this when platform architects, SRE leads, or senior engineers need to create a durable record of config decisions that future maintainers can search and understand.

textCopy
You are a platform architect documenting configuration design decisions for future maintainers. Generate a Config Decision Record (CDR) for the following configuration parameter decision.

## Input
- **Parameter Name:** [PARAMETER_NAME]
- **Configuration Domain:** [CONFIG_DOMAIN]
- **Decision Context:** [DECISION_CONTEXT]
- **System Context:** [SYSTEM_CONTEXT]
- **Constraints:** [CONSTRAINTS]
- **Stakeholders:** [STAKEHOLDERS]
- **Decision Date:** [DECISION_DATE]

## Output Schema
Produce a Config Decision Record with these sections:

### Title
A concise title summarizing the decision.

### Status
One of: Proposed, Accepted, Deprecated, Superseded.

### Context
Describe the forces at play: technical constraints, operational requirements, security posture, cost sensitivity, team capabilities, and any regulatory or compliance factors that shaped this decision.

### Decision
State the exact configuration parameter, its chosen default value or constraint, and the scope where it applies (environment, service, module). Include the parameter type, valid range, and whether it is required or optional.

### Alternatives Considered
For each alternative, provide:
- **Alternative:** What was considered.
- **Pros:** Why it was attractive.
- **Cons:** Why it was rejected.
- **Rejection Reason:** The decisive factor.

Include at least two alternatives. If no alternatives were seriously considered, explain why the chosen value was the only viable option.

### Consequences
Describe what becomes easier, harder, or different because of this decision. Cover:
- Positive consequences (what improves).
- Negative consequences (trade-offs, limitations, new risks).
- Mitigations for negative consequences.
- Migration or rollout implications if this changes an existing default.

### Related Decisions
List related CDRs, ADRs, or design documents by title and link if available. Note dependencies or conflicts.

### Validation
How to verify the decision is working as intended in production. Include specific metrics, alerts, or checks.

## Constraints
- Use precise technical language. Avoid vague qualifiers like "good enough" or "reasonable."
- Quantify trade-offs where possible (e.g., "increases p99 latency by 15ms, reduces memory by 200MB").
- Flag any assumptions that, if invalidated, would require revisiting this decision.
- If the decision has security, compliance, or cost implications, call them out explicitly.
- Do not invent facts. If context is missing, note what information would be needed to strengthen the record.

## Examples
[EXAMPLES]

## Risk Level
[RISK_LEVEL]

Adaptation guidance: Replace each square-bracket placeholder with real values before execution. The [EXAMPLES] placeholder should contain one or two well-formed CDR examples that demonstrate the expected depth and tone. The [RISK_LEVEL] placeholder accepts values like low, medium, high, or critical and should influence how thoroughly the model explores alternatives and consequences. For high-risk or critical decisions, add a human review step after generation: have a second engineer verify that all viable alternatives were considered and that consequences are not understated. Wire this prompt into a documentation pipeline that stores CDRs alongside the config schema or in a dedicated decision log repository with version control.

The Config Decision Record prompt is designed to be integrated into a platform engineering workflow where configuration changes are reviewed before merging. The primary integration point is a pull request check or a pre-commit hook that triggers when files in a config schema directory (e.g., config/schema/, infra/terraform/vars/) are modified. The application harness should extract the diff of the configuration change, the existing ADR directory for context, and the proposed new default or constraint, then assemble the prompt with these inputs. This is not a real-time user-facing prompt; it is a batch documentation generation step that runs in CI/CD pipelines or internal developer platforms like Backstage.

The harness must enforce a strict validation contract on the model's output. The expected output is a Markdown ADR document with specific sections: Title, Status, Context, Decision, Alternatives Considered, Consequences. Use a schema validator (e.g., a JSON schema that checks for the presence of all required headings) before writing the ADR file. If validation fails, implement a single retry with the error message injected into the [CONSTRAINTS] field, instructing the model to repair the missing section. After two failures, the check should fail with a clear log message and block the PR merge. For model choice, a capable mid-tier model like claude-3.5-sonnet or gpt-4o is appropriate; this task requires structured reasoning and trade-off analysis, not just text generation. Do not use a lightweight model for this prompt, as it will likely omit the 'Alternatives Considered' section or produce shallow trade-off analysis.

Logging and observability are critical for auditability. Every generated ADR should be logged with the commit SHA, the config parameter name, the model version used, and the validation status. Store these logs in a structured format (JSON) alongside the generated ADR in a dedicated directory (e.g., docs/adr/config/). This creates an audit trail that links every configuration decision back to the code change and the AI-assisted rationale. For high-risk configuration changes—such as those affecting security defaults, data retention, or authentication behavior—the harness should add a [REQUIRES_HUMAN_REVIEW] label to the generated ADR and automatically assign a review task to the platform architecture team. The prompt's [RISK_LEVEL] placeholder should be populated by a pre-classification step that scans the changed parameter name against a risk registry before the prompt is assembled.