ADR for Incident Postmortem Prompt

This prompt is designed for staff engineers and SRE leads who need to bridge the gap between operational incident response and deliberate architectural governance. The core job-to-be-done is transforming a completed, blameless postmortem into a traceable Architecture Decision Record (ADR) that documents the systemic architectural gap revealed by the incident, the chosen remediation, and the rationale linking the decision directly to the root cause analysis. The ideal user has already completed a thorough postmortem with a confirmed timeline, root cause analysis, and contributing factors. They are now facing the question: 'How do we prevent this class of failure from recurring, and how do we document that decision for future maintainers?'

Use this prompt when the incident exposes a gap that requires a deliberate change to the system's architecture—such as introducing a circuit breaker, changing a data consistency guarantee, splitting a service boundary, or adding a new infrastructure dependency. The prompt forces a structured link between the incident's specific failure mode and the architectural decision, ensuring the ADR's context section cites the incident timeline and root cause, the decision section addresses the identified gap, and the consequences section evaluates whether the chosen solution actually prevents the observed failure. Do not use this prompt for minor bug fixes, standard operational procedure updates, capacity adjustments, or decisions that do not alter the system's fundamental structure or contracts. It is also inappropriate when the postmortem is incomplete, the root cause remains unconfirmed, or the incident was caused by a one-off human error with no architectural dimension.

Before running this prompt, confirm that you have the postmortem document with a finalized timeline, a confirmed root cause, and a clear statement of the architectural gap. The prompt assumes these inputs are available as [POSTMORTEM_DOCUMENT] and [ROOT_CAUSE_SUMMARY]. If the postmortem is still in draft or the root cause is disputed, resolve those uncertainties first. The output ADR should be reviewed by at least one engineer who was not directly involved in the incident response to ensure the decision logic holds up under scrutiny. After generating the ADR, submit it through your team's standard ADR review process and link it to the incident ticket for bidirectional traceability.

This prompt template is designed to produce a complete, standards-compliant ADR from a production incident's postmortem data. It forces the model to connect the incident's root cause directly to a specific architectural decision, ensuring the remediation is traceable and the rationale is preserved for future maintainers. The template is structured to be dropped into any AI harness that accepts system and user messages, with placeholders for your specific incident timeline, root cause analysis, and team context.

textCopy
SYSTEM:
You are a staff engineer documenting an architecture decision that resulted from a production incident. Your output must be a complete Architecture Decision Record (ADR) in the format specified. The decision must directly address the root cause identified in the incident postmortem. Do not propose generic improvements; every recommendation must trace back to a specific finding in the incident timeline or root cause analysis.

USER:
Generate an ADR based on the following incident postmortem data.

INCIDENT TITLE: [INCIDENT_TITLE]
INCIDENT DATE: [INCIDENT_DATE]
INCIDENT SEVERITY: [SEVERITY_LEVEL]
INCIDENT TIMELINE:
[TIMELINE_OF_EVENTS]

ROOT CAUSE ANALYSIS:
[ROOT_CAUSE_DESCRIPTION]

ARCHITECTURAL GAP IDENTIFIED:
[GAP_DESCRIPTION]

PROPOSED REMEDIATION:
[REMEDIATION_PROPOSAL]

AFFECTED COMPONENTS:
[LIST_OF_AFFECTED_COMPONENTS]

CONSIDERED ALTERNATIVES:
[LIST_OF_ALTERNATIVES_CONSIDERED]

TEAM CONTEXT:
[TEAM_OR_ORGANIZATIONAL_CONTEXT]

OUTPUT_SCHEMA:
{
  "adr": {
    "title": "ADR-[NNN]: [Decision Title]",
    "status": "proposed",
    "date": "[ISO_DATE]",
    "incident_link": "[INCIDENT_TICKET_OR_POSTMORTEM_LINK]",
    "context": "Summary of the incident and the architectural gap it exposed.",
    "decision": "The specific architectural change we are making.",
    "considered_alternatives": [
      {
        "alternative": "Description",
        "pros": ["Pro 1"],
        "cons": ["Con 1"],
        "reason_rejected": "Why this was not chosen."
      }
    ],
    "consequences": {
      "positive": ["Easier rollback", "Reduced latency"],
      "negative": ["Increased operational complexity"],
      "mitigations": ["Runbook update for new component"],
      "affected_components": ["Component A", "Component B"]
    },
    "prevention_measures": [
      "Measure that prevents this class of incident from recurring."
    ],
    "validation_criteria": [
      "How we will confirm the decision resolves the root cause."
    ]
  }
}

CONSTRAINTS:
- The 'decision' field must describe a concrete architectural change, not a process change.
- Every 'prevention_measures' entry must directly mitigate the identified root cause.
- The 'considered_alternatives' array must include the option of doing nothing.
- If the incident severity is SEV1 or SEV2, the status must be 'proposed' and require human review before acceptance.

To adapt this template, replace every square-bracket placeholder with data from your incident postmortem. The [TIMELINE_OF_EVENTS] should be a concise, chronological list of what happened, as this provides the model with the causal chain it needs to validate the decision. The [ROOT_CAUSE_DESCRIPTION] is the most critical field; a vague root cause will produce a vague ADR. After pasting the prompt, always run the output through a validation step that checks for the presence of all required ADR fields and confirms that the prevention_measures array is not empty. For high-severity incidents, the generated ADR should be treated as a draft and routed for human engineering review before it is committed to the decision log.

This prompt is designed to sit inside a postmortem or incident-review pipeline, not as a standalone chat interaction. The typical trigger is a completed incident document (timeline, 5-whys, remediation items) plus relevant monitoring data. The harness should assemble these inputs, call the model, validate the output against the ADR schema, and route the result for human engineering review before the ADR is committed to the repository. Do not treat this as a fire-and-forget generation step—the output is an architecture decision record that will be referenced by future maintainers, so correctness and traceability matter more than speed.

Wire the prompt into an application function that accepts an incident_report object (containing timeline, root_cause, impact, remediation_actions) and an optional system_context string (architecture diagrams, recent ADRs, service dependency maps). The function should inject these into the [INCIDENT_DOCUMENT] and [SYSTEM_CONTEXT] placeholders respectively. Set [CONSTRAINTS] to enforce a maximum ADR length, required sections (Context, Decision, Alternatives Considered, Consequences, Prevention), and a rule that every claim must cite a specific incident finding. Use a model with strong structured-output support—GPT-4o or Claude 3.5 Sonnet with JSON mode enabled—and set temperature to 0.2 or lower to reduce creative drift in the decision rationale.

After generation, run a schema validator that checks for the presence of all required ADR fields, verifies that the root_cause referenced in the ADR matches the incident report's root cause, and confirms that every prevention item maps to at least one remediation_action from the incident. If validation fails, retry once with the validation errors injected into the prompt as additional [CONSTRAINTS]. If the second attempt also fails, escalate to a human reviewer with the raw incident document, both failed outputs, and the validator error log. Log every generation attempt, validation result, and reviewer action for auditability. Never auto-commit an incident-informed ADR without human sign-off—these decisions often carry operational risk and budget implications that require engineering judgment.

For teams using an ADR repository (e.g., a docs/decisions/ directory in version control), the harness should prepend the generated ADR with a status of proposed and a metadata block linking to the incident ticket. Only after human review and approval should the status be updated to accepted. If the incident postmortem reveals that a previous ADR was invalidated or needs revision, the harness should flag this and suggest creating a superseding ADR rather than silently editing the original. Avoid wiring this prompt directly into a chatbot or Slack command without the validation and review gates—the risk of generating a plausible but incorrect architecture decision is high when the model lacks full context on system constraints and team capacity.