Breaking Change Impact Radius Estimation Prompt

This prompt is for library maintainers, platform teams, and API owners who are planning a breaking change and need a rigorous, evidence-backed estimate of the downstream blast radius before they ship. The job-to-be-done is not just listing consumers, but producing a structured impact report that identifies every affected API surface, downstream consumer, and the estimated migration effort per consumer, all grounded in source evidence. The ideal user is a senior engineer or architect who can provide the proposed change specification and has access to the codebase or dependency graph.

Use this prompt when the change is material—deprecating a public function, altering a method signature, removing a supported parameter, or changing a serialization contract. It is designed for scenarios where the cost of breaking a downstream consumer is high, such as public SDKs, internal platform services with multiple teams depending on them, or open-source libraries with a broad user base. The prompt requires a detailed [CHANGE_SPECIFICATION] that describes the current and proposed API surface, and a [DEPENDENCY_CONTEXT] that includes the list of known consumers, their usage patterns, or the repository structure to analyze. Without these inputs, the model will hallucinate consumers and produce a useless report.

Do not use this prompt for trivial internal refactors where the blast radius is already known, for changes that are purely additive, or for codebases where you cannot provide a reliable list of downstream consumers. The prompt is also inappropriate when the primary goal is to decide whether to make the change—it estimates impact, not business value. Finally, every consumer identified by the model must be verified by a human before the report is used to communicate migration timelines to dependent teams. The model can miss consumers that use reflection, dynamic invocation, or undocumented internal APIs, so treat the output as a starting point for a manual review, not a final audit.

This is the core prompt template for the Breaking Change Impact Radius Estimation workflow. It is designed to be copied directly into your prompt management system, IDE, or orchestration harness. The template uses square-bracket placeholders for all dynamic inputs, ensuring you can swap in your specific change description, codebase context, and output requirements without altering the instruction structure. The prompt instructs the model to act as a principal architect and produce a source-grounded impact report, not a speculative summary.

textCopy
You are a principal software architect analyzing the impact radius of a proposed breaking change. Your task is to produce a detailed, source-grounded impact estimate. You must identify every downstream consumer, affected API surface, and migration effort. You must not speculate without evidence.

## CHANGE PROPOSAL
[CHANGE_DESCRIPTION]

## CODEBASE CONTEXT
[CODEBASE_CONTEXT]

## CONSTRAINTS
- Identify every downstream consumer (internal modules, external services, public APIs, SDK clients, and configuration files) that will be affected.
- For each consumer, cite the specific file path, function signature, class, or interface that will break.
- Classify each break by severity: CRITICAL (compile-time failure or runtime crash), HIGH (behavioral change without crash), MEDIUM (deprecation warning or optional migration), LOW (cosmetic or documentation-only).
- Estimate the migration effort for each consumer using t-shirt sizes (S, M, L, XL) with a one-sentence justification.
- If the change affects a public API, list every known external integrator from the provided context.
- If the provided context is insufficient to identify all consumers, explicitly state what information is missing and where to find it.
- Do not invent consumers, file paths, or API surfaces not present in the provided context.

## OUTPUT SCHEMA
Return a valid JSON object with the following structure:
{
  "change_summary": "string (one-sentence summary of the breaking change)",
  "total_consumers_affected": "integer",
  "severity_distribution": {
    "critical": "integer",
    "high": "integer",
    "medium": "integer",
    "low": "integer"
  },
  "consumers": [
    {
      "consumer_name": "string",
      "consumer_type": "internal_module | external_service | public_api_client | sdk_user | config_file",
      "affected_artifact": "string (file path, function signature, or API endpoint)",
      "break_description": "string (what will fail and how)",
      "severity": "CRITICAL | HIGH | MEDIUM | LOW",
      "migration_effort": "S | M | L | XL",
      "migration_justification": "string (one sentence)",
      "source_evidence": "string (exact file path, line range, or documentation reference from context)"
    }
  ],
  "missing_information": ["string (list of missing context items needed for complete analysis)"],
  "recommended_mitigation": "string (summary of rollout strategy, deprecation window, or migration tooling)"
}

## EXAMPLES
[FEW_SHOT_EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

To adapt this template, replace each square-bracket placeholder with concrete values before sending it to the model. [CHANGE_DESCRIPTION] should contain the full breaking change proposal, including the old and new signatures, behavioral differences, and the rationale. [CODEBASE_CONTEXT] must include the relevant source files, import graphs, API specifications, or dependency manifests that the model will use as ground truth. If you have a large codebase, pre-filter the context to only the modules and consumers within the blast radius of the change; do not dump the entire repository into the prompt. [FEW_SHOT_EXAMPLES] should contain one or two example input-output pairs showing the expected analysis depth and citation style. [RISK_LEVEL] should be set to HIGH, MEDIUM, or LOW to calibrate the model's conservatism. For high-risk changes, add an explicit instruction to flag any consumer where the migration effort is XL for mandatory human review before proceeding.

This prompt is designed to be integrated into a library or platform team's release pipeline, not run as a one-off chat. The implementation harness must enforce source grounding for every consumer identified, validate the output schema before accepting results, and provide clear logging for auditability. Because the output directly informs migration communication and deprecation timelines, the harness should treat the prompt as a structured data generator with strict post-processing, not as a free-text advisor.

Wire the prompt into an automated workflow that feeds it a structured [CHANGE_DESCRIPTION] and a [CODEBASE_MANIFEST] containing import graphs, API usage data, or dependency declarations. The harness should first validate that the manifest is non-empty and recent enough to be useful—stale data produces false negatives. After the model responds, run a schema validator against the expected JSON output shape: a top-level consumers array where each entry has consumer_name, affected_api_surfaces, estimated_migration_effort, and source_evidence. Reject any output where source_evidence is missing, vague, or hallucinated by cross-referencing against the provided manifest. If validation fails, retry once with a repair prompt that includes the specific validation errors. If the retry also fails, escalate to a human reviewer with the raw output and failure reasons logged.

Model choice matters here. Use a model with strong structured output support and a large context window if the manifest is substantial. For very large codebases, pre-filter the manifest to only include modules that import or depend on the changed surface area before passing it to the prompt—this reduces noise and token cost. Log every run with the prompt version, manifest hash, model used, validation results, and final output. This audit trail is essential when downstream teams question why they were or were not flagged. Avoid running this prompt in a fully automated gate that blocks releases; it should inform decisions, not make them.