Change Propagation Risk Analysis Prompt

This prompt is for architects and platform engineers who need to evaluate the downstream impact of a proposed change to a single service before writing code. It produces a structured impact map identifying every affected service, API endpoint, event topic, and data store, with risk scores and a recommended integration test scope. Use it during design review, sprint planning, or as a gate before merging a breaking change proposal.

The ideal user has access to a current service dependency graph, API specifications, event schemas, and data ownership documentation. The prompt requires these artifacts as input because it reasons over concrete contracts, not assumptions. Without them, the model will hallucinate dependencies and produce a false sense of security. The prompt is designed for changes with contract implications—schema modifications, endpoint deprecations, event payload changes, or data model migrations—not cosmetic refactors or logging additions that don't cross service boundaries.

Do not use this prompt when the system architecture is undocumented, when the change is purely cosmetic with no contract implications, or when you need a real-time production dependency graph rather than a design-time analysis. The output is a planning artifact, not a runtime topology. For high-risk changes in regulated domains, always route the impact map through a human architecture review before accepting the recommended test scope. The prompt identifies propagation paths; it does not replace integration testing or canary deployment validation.

The following prompt template is designed to be pasted directly into your AI system. It instructs the model to adopt the persona of a systems architect and perform a structured analysis of how a proposed change to one service will propagate across the entire system. The output is an impact map identifying all affected services, APIs, events, and data stores, complete with risk scores and a recommended integration test scope. Replace every square-bracket placeholder with the specific details of your system and the change being proposed before execution.

textCopy
You are a systems architect specializing in distributed systems and microservice risk analysis. Your task is to perform a rigorous change propagation analysis for a proposed modification.

## System Context
[SYSTEM_ARCHITECTURE_DESCRIPTION]

## Proposed Change
Service to modify: [SERVICE_NAME]
Change description: [CHANGE_DESCRIPTION]
Proposed changes to API contracts, event schemas, or data models: [CONTRACT_CHANGES]

## Analysis Instructions
1.  **Dependency Mapping:** Identify every downstream service, API consumer, event subscriber, and data store that depends on [SERVICE_NAME] or the artifacts being changed.
2.  **Impact Assessment:** For each identified dependency, describe the specific impact of the proposed change. Classify the impact as **Breaking**, **Degrading**, or **Transparent**.
3.  **Risk Scoring:** Assign a risk score (1-5, where 5 is critical) to each impacted component based on the severity of the impact and the criticality of the component.
4.  **Test Scope Recommendation:** Define the minimum required integration test scope to validate the change safely, specifying which service interactions must be tested.
5.  **Migration Sequencing:** If the change is breaking, propose a sequenced migration plan (e.g., two-phase deployment, feature flags, API versioning) to minimize blast radius.

## Output Format
Produce a single JSON object conforming to this exact schema:
{
  "change_id": "string",
  "analysis_summary": "string",
  "impact_map": [
    {
      "impacted_component": "string",
      "dependency_type": "API | Event | Database | Config",
      "impact_description": "string",
      "impact_classification": "Breaking | Degrading | Transparent",
      "risk_score": "number (1-5)",
      "recommended_action": "string"
    }
  ],
  "breaking_changes_detected": "boolean",
  "recommended_integration_test_scope": ["string"],
  "migration_sequence": ["string"]
}

## Constraints
- Only report on components explicitly mentioned in or directly inferable from the provided system context.
- If the change description is ambiguous, state your assumptions clearly in the `analysis_summary`.
- Do not invent dependencies or system components not described in the context.

To adapt this template, replace the [SYSTEM_ARCHITECTURE_DESCRIPTION] placeholder with a detailed description of your system's components, their interactions, and data flows. This context is critical for accurate dependency mapping. The [CHANGE_DESCRIPTION] and [CONTRACT_CHANGES] placeholders must be filled with precise, technical details of the modification. The output schema is strictly enforced in the prompt to ensure the result can be parsed by downstream automation. For high-risk changes, the generated impact_map and migration_sequence should be treated as a starting point for a formal architecture review, not a final decision. Always log the full prompt and response for auditability.

This prompt is designed to be integrated into an architecture review pipeline, not used as a one-off chat interaction. The implementation harness should treat the prompt as a deterministic analysis step that takes a structured change proposal and a service dependency graph as inputs, and returns a machine-readable impact map. Because the output directly informs integration test scope and release gating decisions, the harness must enforce schema validation, handle model non-determinism, and provide a clear audit trail linking each risk score to the evidence used to produce it.

Wire the prompt into an application by first assembling the [SERVICE_DEPENDENCY_GRAPH] from your service catalog, API gateway configs, event registry, and data lineage tools. This graph should be a machine-generated input, not hand-written, to avoid drift between the analysis and reality. The [CHANGE_PROPOSAL] should come from a structured form or PR template that captures the affected service, the type of change (schema, contract, data model, protocol, dependency version), and the blast radius intent. Before calling the model, validate both inputs against their expected schemas. After receiving the model response, run strict JSON schema validation on the output. If validation fails, retry once with the validation errors appended to the prompt as [PREVIOUS_ERRORS]. If the retry also fails, route the request to a human architect for manual review rather than silently accepting a malformed impact map.

Model choice matters here. Use a model with strong reasoning capabilities and reliable structured output support. Configure the request with response_format set to json_schema (OpenAI) or equivalent structured output mode, and provide the full expected schema. Set temperature low (0.1-0.2) to reduce variance in risk scoring. Log every request and response pair, including the validated output, the model version, and the timestamp, to an immutable audit store. This log becomes evidence for compliance reviews and post-incident analysis. For high-risk changes—those touching payment, auth, or data deletion paths—add a mandatory human approval gate after the impact map is generated. The approval step should present the impact map alongside the original change proposal and require sign-off before integration tests are scoped or the change proceeds.

Do not use this prompt as a real-time gate in a CI/CD pipeline without caching. The model call adds latency and cost. Instead, run it as an asynchronous analysis triggered by a change proposal event. Cache the dependency graph with a known version identifier and include that version in the prompt's [SERVICE_DEPENDENCY_GRAPH] section so stale-graph analyses are detectable. When the service topology changes, invalidate the cache and re-run any pending analyses. Avoid wiring the prompt directly to automated deployment blockers until you have at least 50 reviewed outputs where you've measured false-positive and false-negative risk assignments against actual production incidents. Premature automation here creates a bottleneck that engineers will route around.

For teams using RAG, do not retrieve dependency information at prompt time from unstructured docs. The dependency graph must be authoritative and pre-assembled. If you lack a formal service catalog, invest in building one before operationalizing this prompt. The quality floor of the analysis is set by the accuracy of the input graph, not by prompt engineering.