Consequences Documentation Prompt for ADRs

This prompt is for staff engineers and technical architects who have already drafted the core sections of an Architecture Decision Record (ADR)—context, decision, and considered alternatives—and now need to rigorously document the ripple effects of that decision. The job-to-be-done is to produce a structured 'Consequences' section that moves beyond a simple pros-and-cons list to capture positive outcomes, negative trade-offs, explicit mitigation strategies, and a clear map of affected system components. The ideal user has the decision's full context and understands the system's current architecture well enough to validate the model's output against reality.

Use this prompt when the decision's scope is clear but its downstream impact needs to be systematically explored and recorded for future maintainers. It is particularly valuable for decisions involving cross-cutting concerns like data model changes, API contract modifications, or infrastructure shifts where the blast radius is large. Do not use this prompt as a substitute for the initial decision-making process itself; it documents consequences, not the decision rationale. Avoid it for trivial, low-impact decisions where the overhead of a full consequences analysis would slow the team down without adding meaningful traceability. The prompt requires a complete [DECISION_SUMMARY], [CONSIDERED_ALTERNATIVES], and [SYSTEM_CONTEXT] as inputs—garbage in, garbage out applies here with force.

Before running this prompt, ensure the ADR's context and decision sections are finalized and approved. The output should be treated as a draft that requires human review, especially for the accuracy of affected components and the feasibility of proposed mitigations. After generating the consequences section, validate it against the original decision scope using the completeness checks described in the evaluation harness, and be prepared to iterate on mitigation strategies with the team before the ADR is accepted.

This template produces the Consequences section of an ADR by forcing the model to reason about ripple effects across positive outcomes, negative trade-offs, mitigation strategies, and affected components. Use it when you have a completed decision statement and context but need a structured, searchable consequences record that future maintainers can rely on. Do not use this prompt for initial decision-making or alternative evaluation—those require separate ADR prompts that precede this step.

textCopy
You are a staff engineer documenting the consequences of an architecture decision for a permanent Architecture Decision Record (ADR).

Your task is to produce only the "Consequences" section of the ADR. Do not repeat the decision title, context, or alternatives unless they are directly relevant to a specific consequence.

# INPUTS

[DECISION_SUMMARY]
[CONTEXT]
[CONSIDERED_ALTERNATIVES]
[SYSTEM_COMPONENTS]
[CONSTRAINTS]

# OUTPUT REQUIREMENTS

Produce a Consequences section with exactly these subsections, in order:

## Positive Outcomes
- List each positive outcome as a bullet point.
- For each outcome, explain what becomes easier, faster, cheaper, or more reliable.
- Link each outcome to the specific decision element that enables it.

## Negative Trade-offs
- List each negative trade-off as a bullet point.
- For each trade-off, explain what becomes harder, slower, more expensive, or riskier.
- State whether the trade-off is accepted, partially mitigated, or deferred.

## Mitigation Strategies
- For each accepted or partially mitigated negative trade-off, describe the mitigation.
- Include concrete actions, tooling, process changes, or future work that reduces the impact.
- If a trade-off is accepted without mitigation, state the rationale explicitly.

## Affected Components
- List every system component, service, or interface affected by this decision.
- For each component, describe the nature of the impact (changed API, new dependency, increased load, deprecated function, new responsibility).
- Flag any component that requires immediate action versus eventual adaptation.

## Second-Order Effects
- Identify consequences that may emerge later as the system evolves.
- Cover scaling limits, team topology changes, vendor lock-in risks, and future migration costs.
- State which effects are speculative and which are near-certain.

# RULES

- Every claim must be traceable to the provided [DECISION_SUMMARY], [CONTEXT], or [CONSIDERED_ALTERNATIVES].
- If a consequence is uncertain, mark it with "[LIKELY]" or "[SPECULATIVE]" and explain the condition that would trigger it.
- Do not invent components, constraints, or alternatives not present in the inputs.
- If the inputs lack enough detail to assess a category, write "Insufficient information to assess" rather than guessing.
- Use precise technical language appropriate for an engineering audience.
- Keep the total output under 800 words unless the decision scope demands more.

[OUTPUT_SCHEMA]
[RISK_LEVEL]

Adapt this template by replacing each square-bracket placeholder with concrete inputs. The [DECISION_SUMMARY] should contain the one-paragraph decision statement from the ADR header. [CONTEXT] should include the problem statement, constraints, and assumptions that shaped the decision. [CONSIDERED_ALTERNATIVES] should list the options that were evaluated and rejected, with brief reasons. [SYSTEM_COMPONENTS] should enumerate the services, databases, APIs, and infrastructure pieces in scope. [CONSTRAINTS] should capture non-functional requirements like latency budgets, compliance requirements, or team skill constraints. The optional [OUTPUT_SCHEMA] placeholder can specify a JSON structure if you need machine-readable consequences for downstream tooling. The [RISK_LEVEL] placeholder accepts values like "low," "medium," or "high" to adjust the depth of second-order effect analysis—higher risk levels demand more thorough speculation about future failure modes.

Before integrating this prompt into a pipeline, validate that the generated consequences section passes a completeness check: every affected component from [SYSTEM_COMPONENTS] should appear in the Affected Components subsection, every trade-off from [CONSIDERED_ALTERNATIVES] should have a corresponding entry in Negative Trade-offs, and no mitigation should be proposed without a linked trade-off. For high-risk decisions, route the output to a human reviewer who can verify that second-order effects are neither overstated nor overlooked. If you are generating multiple ADRs, run a consistency check across consequences sections to catch contradictory assumptions about component ownership or interface contracts.

The Consequences Documentation Prompt is designed to be called after the core decision, context, and alternatives sections of an ADR are already drafted. In a typical implementation, the application layer assembles the decision record, extracts the decision scope and considered alternatives, and passes them as structured inputs to the prompt. The model then produces a consequences section that covers positive outcomes, negative trade-offs, mitigation strategies, and affected components. Because this output becomes part of a permanent architecture record, the harness must enforce completeness, consistency, and traceability before the ADR is accepted.

Wire the prompt into a documentation pipeline that first validates the input: confirm that [DECISION_SUMMARY], [ALTERNATIVES_CONSIDERED], and [AFFECTED_COMPONENTS] are non-empty and contain enough detail to ground the consequences analysis. After the model returns the consequences text, run a completeness validator that checks for required subsections (positive outcomes, negative trade-offs, mitigation strategies, affected components) and flags any missing sections. Follow this with a scope alignment check that compares the consequences against the original decision scope—if the model introduces consequences for components not listed in [AFFECTED_COMPONENTS], flag them for architect review. For high-risk or regulated domains, route the output to a human approval queue before the ADR is merged. Log the prompt version, model, input hashes, and validator results for auditability.

Model choice matters here. Use a model with strong reasoning and structured output capabilities (such as Claude 3.5 Sonnet or GPT-4o) and set a low temperature (0.0–0.2) to maximize consistency across ADR runs. If the validator rejects the output, implement a single retry with the validation errors appended as [CONSTRAINTS] feedback—do not loop indefinitely. For teams maintaining large ADR repositories, consider storing the consequences output alongside the decision record with a consequences_generated_by metadata field that includes the model version and prompt hash. Avoid using this prompt for decisions that are still in active debate; the input must represent a settled decision with clear scope, or the consequences analysis will be speculative and unreliable.