ADR Stakeholder Impact Analysis Prompt

Use this prompt when a draft Architecture Decision Record (ADR) is stable enough to share but not yet approved. The primary job-to-be-done is preventing the most common governance failure in software architecture: surprising the teams who must operate, integrate with, or migrate under the new decision. The ideal user is an engineering lead, staff engineer, or architect who owns the decision and needs to communicate its blast radius before locking it in. Required context includes the full draft ADR text, a list of known stakeholder teams or roles, and any organizational context about team responsibilities, on-call rotations, and delivery schedules.

This prompt is designed for decisions that cross team boundaries. A database technology change, a new service extraction, an authentication framework migration, a logging standard mandate, or a deprecation of a shared internal API are all strong candidates. The prompt works by forcing the model to reason about who is affected, how severely, what communication they need, and what migration burden they carry. It produces a structured impact matrix rather than free-text commentary, which makes it suitable for attaching to the ADR as an appendix or using as a pre-review checklist. Do not use this prompt for decisions contained entirely within a single team with no external consumers, or for trivial changes where the impact is already obvious to all parties. It is also not a substitute for actually talking to stakeholders; it is a preparation step that makes those conversations more productive.

Before running the prompt, ensure the draft ADR includes a clear statement of the decision, the context that motivated it, and the options that were considered. If the ADR is vague about what is changing, the impact analysis will be vague too. After receiving the output, review it for missing stakeholders—the model can only identify parties you have described or implied in the input. Pay special attention to commonly overlooked groups: SRE teams inheriting new on-call surfaces, security teams needing to update threat models, compliance officers tracking audit controls, and product teams whose roadmaps depend on the affected systems. Use the resulting matrix to plan communication, schedule migration checkpoints, and update the ADR's consequences section before final approval.

This prompt template is designed to be pasted directly into your AI harness. It takes a complete or draft Architecture Decision Record (ADR) and produces a structured stakeholder impact matrix. The prompt instructs the model to identify affected parties, assess change severity, define communication needs, and estimate migration burden. It also includes a specific coverage check for commonly overlooked stakeholders like SRE, security, and support teams.

textCopy
You are an experienced software architect and organizational analyst. Your task is to perform a thorough stakeholder impact analysis based on the provided Architecture Decision Record (ADR).

## INPUT
[ADR_DOCUMENT]

## INSTRUCTIONS
1.  **Identify Stakeholders:** List every team, role, system, or external party affected by this decision. Go beyond the obvious engineering teams. Consider operations, security, support, product, sales, legal, and end-users.
2.  **Assess Impact:** For each stakeholder, determine the severity of the impact (High, Medium, Low) and describe the nature of the change (e.g., new workflow, API deprecation, schema migration, retraining required).
3.  **Define Communication Needs:** Specify what each stakeholder needs to know, the best channel for communication (e.g., email, team meeting, API changelog), and the recommended timing (e.g., at decision, before implementation, at release).
4.  **Estimate Migration Burden:** For stakeholders with a High or Medium impact, estimate the effort required to adapt (e.g., person-weeks, system downtime, data migration complexity).
5.  **Coverage Check:** Explicitly check for the following commonly overlooked stakeholders and include them if relevant: Site Reliability Engineering (SRE), Database Administrators (DBAs), Customer Support, Legal/Compliance, and Data Science/Analytics teams.

## OUTPUT_SCHEMA
Your response must be a single valid JSON object with the following structure. Do not include any text outside the JSON object.
{
  "decision_title": "string",
  "analysis_summary": "string (2-3 sentence executive summary of the overall impact)",
  "stakeholder_impacts": [
    {
      "stakeholder_name": "string",
      "impact_severity": "High | Medium | Low",
      "change_description": "string",
      "communication_needs": "string",
      "communication_channel": "string",
      "communication_timing": "string",
      "migration_burden_estimate": "string (provide if High or Medium severity, otherwise null)"
    }
  ],
  "overlooked_stakeholders_found": [
    {
      "stakeholder_name": "string",
      "was_initially_overlooked": true,
      "reason_for_inclusion": "string"
    }
  ]
}

## CONSTRAINTS
- Base your analysis strictly on the provided [ADR_DOCUMENT]. Do not invent stakeholders or impacts not implied by the text.
- If the ADR lacks sufficient detail to assess a dimension, set the relevant field to "Insufficient information in ADR" and note it in the analysis_summary.
- Be specific. Instead of "teams need to update things," write "Backend API teams must update service clients to use the new v2 endpoint and retire v1 calls by Q3."
- The `overlooked_stakeholders_found` list must only contain stakeholders that were not explicitly mentioned in the ADR but are clearly impacted.

To adapt this template, replace the [ADR_DOCUMENT] placeholder with the full text of your ADR. The prompt is designed for a single-turn generation task. For high-risk architectural decisions, the output JSON should be reviewed by a human architect or program manager before being used to drive communication plans. You can integrate this prompt into a CI/CD pipeline by adding a validation step that checks the JSON schema and flags any impact_severity of "High" for mandatory human review.

This prompt is designed to be called programmatically as part of an architecture review pipeline, not as a one-off chat interaction. The primary integration point is after an ADR draft is written but before it is approved. The application should supply the full ADR text and a structured list of known stakeholders, teams, and systems as [CONTEXT]. The model returns a structured impact matrix that downstream systems can parse, store, and display. Because the output affects team planning and communication, the harness must validate the response before it reaches a human reviewer or an automated notification system.

Implement the harness with a schema validation gate before accepting the output. The expected output is a JSON object containing an impact_matrix array where each entry has stakeholder, role, impact_severity (one of high, medium, low, none), change_description, communication_needs, and migration_burden. Use a JSON Schema validator in your application code to reject malformed responses. If validation fails, retry once with the same prompt plus the validation error message appended as a correction instruction. If the retry also fails, log the failure and escalate to a human reviewer with the raw output attached. Do not silently accept unparseable impact data.

For model choice, prefer a model with strong structured output capabilities and a large context window, since ADRs plus stakeholder lists can be lengthy. If your ADR repository is large, consider using retrieval-augmented generation (RAG) to pull in relevant past ADRs and their stakeholder impact records as few-shot examples. Store validated impact matrices in a database keyed by ADR ID and version. This enables historical comparison: when an ADR is superseded, the harness can diff the old and new impact matrices to highlight which stakeholders experience a change in severity or burden.

Logging and observability are critical. Log the prompt version, model used, input token count, output token count, validation pass/fail, retry count, and any human escalation events. If the prompt is used in a CI/CD gate for ADR approval, emit a structured check result that the pipeline can consume. Include a coverage_warning field in the output schema that flags when the model detects a stakeholder mentioned in the ADR body that was not in the provided stakeholder list. This prevents silent omissions. Always require human sign-off on the impact matrix before it is distributed to affected teams, especially when migration burden is rated high or communication needs include training or budget approval.