ADR Status Update Prompt Template

This prompt is for engineering leads and architects who need to transition an existing Architecture Decision Record (ADR) through its lifecycle states: proposed, accepted, deprecated, or superseded. The primary job-to-be-done is producing a structured, auditable status change record that captures the rationale for the transition, an impact assessment on downstream systems and teams, and notification guidance for affected stakeholders. The ideal user is a technical decision maker who already has an approved or previously recorded ADR and a clear, defensible reason for changing its state—such as new evidence, a shift in organizational strategy, or the adoption of a replacement decision.

Use this prompt when your ADR repository enforces a state machine and you need a consistent, machine-readable record of every transition. The prompt includes validation logic to reject invalid transitions, such as moving directly from proposed to deprecated without an intermediate accepted or rejected state. It assumes you can provide the existing ADR content, the target state, and the triggering context. Do not use this prompt to generate a new ADR from scratch; use the ADR Generation Prompt Template for that. Do not use it to compare multiple architectural options; use the ADR Comparison Prompt for Trade-Off Analysis instead. This prompt is specifically scoped to lifecycle state changes and the documentation required to make those changes traceable.

Before using this prompt, ensure you have the current ADR text, its current state, and a clear understanding of why the state must change. The output will include a structured status change record, an impact matrix for downstream systems and teams, and a notification plan. If the transition is high-risk—such as deprecating a decision that underpins critical infrastructure—the prompt will flag the need for human review and stakeholder sign-off. After generating the status update, the next step is to commit the record to your ADR repository, notify the identified stakeholders, and update any dependent decision records that reference the changed ADR.

The prompt below produces a status change record for an Architecture Decision Record (ADR). It enforces valid state transitions, requires rationale for the change, assesses the impact on downstream decisions and affected teams, and generates notification guidance. Replace every square-bracket placeholder with concrete values before sending the prompt to the model. The template is designed to be wired into a CI/CD pipeline, a documentation workflow, or an ADR management tool where lifecycle tracking is required.

textCopy
You are an architecture documentation specialist responsible for maintaining the integrity of an ADR repository. Your task is to generate a structured ADR status change record.

## INPUT
- Current ADR: [ADR_TITLE]
- Current ADR Status: [CURRENT_STATUS]
- Proposed New Status: [PROPOSED_STATUS]
- Change Rationale (raw notes): [RATIONALE_NOTES]
- Affected Systems or Components: [AFFECTED_SYSTEMS]
- Stakeholders to Notify: [STAKEHOLDER_LIST]
- Related ADR References: [RELATED_ADRS]
- Change Author: [AUTHOR_NAME]
- Change Date: [CHANGE_DATE]

## CONSTRAINTS
- Valid status transitions are:
  - Proposed -> Accepted
  - Proposed -> Rejected
  - Proposed -> Superseded
  - Accepted -> Deprecated
  - Accepted -> Superseded
  - Deprecated -> Superseded
- If [PROPOSED_STATUS] is not a valid transition from [CURRENT_STATUS], respond with an error object and do not generate a status change record.
- The rationale must reference specific evidence, events, or new information that triggered the change. Do not accept vague justifications like "team decided" without supporting detail.
- Impact assessment must cover: downstream ADRs that reference this decision, systems that depend on the architecture described, and teams that must adjust their work.
- Notification guidance must specify which stakeholders need what level of detail (full record vs. summary vs. awareness-only).

## OUTPUT_SCHEMA
Return a JSON object with this structure:
{
  "status_change_record": {
    "adr_title": "string",
    "previous_status": "string",
    "new_status": "string",
    "transition_valid": true,
    "rationale_summary": "string (2-4 sentences capturing the core reason)",
    "detailed_rationale": "string (full explanation with evidence references)",
    "impact_assessment": {
      "downstream_adrs_affected": ["string"],
      "systems_affected": ["string"],
      "teams_affected": ["string"],
      "migration_required": true,
      "migration_notes": "string (if migration_required is true, describe what changes are needed)"
    },
    "notification_plan": [
      {
        "stakeholder": "string",
        "detail_level": "full_record | summary | awareness_only",
        "communication_channel": "string (e.g., PR comment, Slack, email, ADR review meeting)"
      }
    ],
    "superseded_by": "string | null (ADR reference if status is Superseded)",
    "author": "string",
    "date": "string"
  }
}

If the transition is invalid, return:
{
  "error": {
    "type": "invalid_transition",
    "current_status": "string",
    "proposed_status": "string",
    "allowed_transitions_from_current": ["string"],
    "message": "string (explaining why the transition is not allowed and suggesting valid alternatives)"
  }
}

## RISK_LEVEL
Medium. Incorrect status changes can cause teams to act on deprecated decisions or miss critical updates. Always validate the transition before generating the record.

Adaptation guidance: If your ADR tooling uses different status labels, update the valid transitions list in the CONSTRAINTS block. If you need the output in Markdown instead of JSON for a documentation site, replace the OUTPUT_SCHEMA with a Markdown template. For high-compliance environments, add a [REVIEWER] placeholder and require a second human sign-off before the status change is applied. The impact assessment fields can be expanded to include cost estimates, timeline impacts, or risk registers if your organization tracks those dimensions.

What to do next: After generating the status change record, validate the JSON output against the schema before persisting it. If the transition is invalid, surface the error to the user with the allowed transitions listed. For accepted records, trigger the notification plan—post comments on related ADRs, notify affected teams via the specified channels, and update any dashboards or indexes that track ADR status. Do not silently apply status changes without confirmation when the RISK_LEVEL is Medium or higher.

The ADR Status Update prompt is designed to be called programmatically, not just used in a chat interface. It expects structured inputs—current status, target status, rationale, and impact assessment—and must return a valid status change record. The primary integration point is a function that assembles the prompt, calls the model, validates the output against the ADR state machine, and either writes the update or rejects the transition. This prompt should be wired into your ADR management tool, CI/CD pipeline, or documentation workflow where status changes trigger notifications, dependency checks, and audit log entries.

State machine validation is the critical harness component. Before calling the model, validate that the requested transition is legal. A proposed ADR can move to accepted, rejected, or deprecated. An accepted ADR can move to deprecated or superseded. A rejected ADR should not transition without explicit override. Implement this as a pre-flight check in your application code—do not rely on the model to enforce it. After receiving the model's output, validate the returned previous_status and new_status fields match the expected transition. If the model hallucinates an invalid transition, retry once with a stronger constraint in the prompt, then escalate for human review if the second attempt also fails. Log every transition attempt, including rejected ones, for auditability.

Output validation should check structure, not just status. Parse the model's JSON response and verify required fields: adr_id, previous_status, new_status, rationale_summary, impact_assessment, affected_adrs, notification_targets, and superseded_by (when applicable). Use a JSON Schema validator in your application layer. If the output fails schema validation, feed the validation errors back into a repair prompt rather than silently accepting malformed data. Human approval gating is recommended for transitions that affect accepted or superseded ADRs, or any transition where the impact assessment flags breaking changes. Route these to a review queue before the status change is committed.

Model choice and temperature matter. Use a model with strong instruction-following and JSON output capabilities (GPT-4o, Claude 3.5 Sonnet, or equivalent). Set temperature to 0 or near-zero to maximize consistency in status field values and rationale structure. If your ADR repository is large, consider providing only the relevant subset of dependent ADRs in the [DEPENDENT_ADRS] placeholder rather than the entire repository, to keep context manageable and reduce hallucination risk. Do not use this prompt with small or local models that struggle with structured output and multi-field consistency—the state machine enforcement is too brittle for unreliable JSON generation.

Wire notifications from the output, not from the prompt. The model returns a notification_targets array with suggested audiences and channels. Your application should read this field and trigger actual notifications through your existing systems (Slack, email, webhook). Never give the model direct access to notification-sending tools. The affected_adrs field should trigger automated checks: if any listed ADR has a conflicting status or dependency, flag it for human review before the update is finalized. Version the prompt template alongside your ADR schema. When you add new statuses or fields, update both the prompt and the validation harness in the same change, and run regression tests against known transition examples before deploying.