Change Propagation Analysis Prompt

This prompt is for maintainers of shared libraries, monorepo owners, and platform teams who need to understand the full downstream impact of a proposed change before committing to it. The job-to-be-done is risk assessment: you are considering a change to a module's public surface—whether a signature modification, a behavioral contract shift, or a deprecation—and you need to know which consumers will break, which will need updates, and how the change cascades through the dependency graph. The ideal user provides two inputs: a structured description of the changed module's public API surface (what is being added, removed, or modified) and a dependency graph showing direct dependents and their consumers. Use this prompt during API deprecation planning, when evaluating whether a seemingly internal refactor will leak into downstream consumers, or before committing to a breaking change that requires coordinated consumer updates.

This prompt does not replace build verification, integration tests, or actual consumer communication. It is a planning tool that produces a propagation map with breakage likelihood assessments and suggested consumer updates. The output is only as reliable as the dependency graph you provide—if your graph is incomplete, stale, or missing indirect dependents, the propagation map will contain false negatives. The prompt assumes you can articulate the change in terms of public contracts: exported functions, classes, interfaces, type signatures, or behavioral guarantees. It is not designed for changes that are purely internal implementation details with no observable effect on consumers, nor for changes where the dependency graph is unknown or must be inferred from source code by the model itself.

Before using this prompt, assemble your dependency graph and change description. After receiving the propagation map, validate it against your own knowledge of the codebase—look for missed indirect dependents, overestimated propagation scope, and consumers flagged as affected that are actually insulated by abstraction layers. The next step is to use the propagation map to plan your rollout: identify which consumers need advance notice, which need code changes, and whether compatibility shims or deprecation windows are required. Avoid treating the propagation map as a final answer; it is a starting point for impact analysis that must be verified against build systems, test suites, and consumer communication channels.

This template is the core instruction set for the Change Propagation Analysis Prompt. It is designed to be pasted into your AI coding agent, LLM workflow, or evaluation harness. The prompt instructs the model to act as a static analysis and dependency reasoning engine, producing a structured propagation map from a single, well-defined change in a shared library or monorepo module. The output is not a patch; it is a risk assessment and consumer impact plan that engineering leads can review before any code is written.

codeCopy
You are a senior software architect specializing in monorepo maintenance and shared library API design. Your task is to analyze a proposed change in one module and produce a detailed propagation map showing how this change cascades through all direct and indirect dependents.

# INPUTS
- [SOURCE_MODULE]: The module where the change originates.
- [CHANGE_DESCRIPTION]: A precise description of the proposed change (e.g., function signature change, removed export, altered default behavior, new required parameter).
- [DEPENDENCY_GRAPH]: A representation of the dependency graph, listing dependents and their relationships. This can be a raw adjacency list, a JSON structure, or the output of a tool like `nx graph` or `madge`.
- [CONSUMER_USAGE_PATTERNS]: (Optional) A summary of how key dependents currently use the changed symbol, derived from static analysis or grep results.

# OUTPUT SCHEMA
Return a single JSON object with the following structure:
{
  "source_change": {
    "module": "string",
    "description": "string",
    "breaking": boolean
  },
  "propagation_map": [
    {
      "dependent_module": "string",
      "dependency_path": ["string"],
      "breakage_likelihood": "high" | "medium" | "low" | "none",
      "impact_rationale": "string",
      "affected_symbols": ["string"],
      "suggested_consumer_update": "string"
    }
  ],
  "indirect_dependents_risk_summary": "string",
  "recommended_change_order": ["string"]
}

# CONSTRAINTS
- Do not invent dependents not present in [DEPENDENCY_GRAPH].
- If a dependent uses the changed symbol, mark breakage_likelihood as "high" for breaking changes and "medium" for behavioral changes.
- For indirect dependents (dependents of dependents), assess risk based on whether the intermediate module re-exports or wraps the changed symbol.
- If [CONSUMER_USAGE_PATTERNS] is provided, use it to refine the impact_rationale. Otherwise, state assumptions clearly.
- The recommended_change_order must respect the dependency graph, listing leaf dependents first.

To adapt this template, replace the square-bracket placeholders with data from your repository tooling. The [DEPENDENCY_GRAPH] is the most critical input; it must be accurate to prevent the model from hallucinating dependents. For a monorepo, you can generate this from Nx project graphs, Turborepo pipelines, or a simple script that parses package.json files. The [CONSUMER_USAGE_PATTERNS] placeholder is optional but strongly recommended for reducing false positives. Populate it by running a grep or static analysis tool (like ts-morph or ast-grep) to find actual call sites of the symbol being changed. Before integrating this prompt into a CI pipeline, run it against known historical changes and compare the output to actual breakage incidents to calibrate your eval thresholds.

The Change Propagation Analysis prompt is designed to be called programmatically, not just used in a chat interface. In a production harness, the prompt receives a structured input payload containing the changed module signature, the dependency graph (or instructions for the agent to retrieve it), and the output schema. The harness is responsible for assembling this context before the model call. For monorepo or shared-library workflows, the dependency graph should be extracted from a build system (e.g., tsconfig.json references, Cargo.toml dependencies, Bazel BUILD files) rather than relying on the model to infer it from source alone. This prevents hallucinated dependencies and ensures the propagation map is grounded in the actual build graph.

After the model returns the propagation map, the harness must validate the output against the expected schema. Key validation checks include: (1) every listed dependent must exist in the provided dependency graph, (2) no circular propagation paths should appear unless the graph itself contains cycles, (3) breakage likelihood scores must fall within the defined range (e.g., 0.0–1.0), and (4) suggested consumer updates must reference real symbols or file paths from the codebase. If validation fails, the harness should retry with the error details appended to the prompt as a correction hint. A maximum of two retries is recommended before escalating to a human reviewer. For high-risk changes—such as public API modifications in shared libraries—the harness should route the validated propagation map to a review queue where a maintainer can confirm or reject the analysis before any code is written.

Model choice matters for this prompt. The task requires reasoning over structured dependency data and producing a consistent, schema-conforming output. Models with strong JSON mode and long-context handling (e.g., Claude 3.5 Sonnet, GPT-4o) perform well. Avoid models that struggle with structured output or tend to hallucinate symbols. For CI integration, wrap the prompt call in a lightweight function that accepts a diff or commit SHA, extracts the changed module, queries the build graph, calls the model, validates the output, and posts the propagation map as a comment on the pull request or merge request. Log every model call with the input context, raw output, validation result, and any retry attempts. This traceability is essential for debugging false negatives—where an indirect dependent is missed—and false positives—where the model overestimates propagation scope. Start with a dry-run mode that posts the analysis as a non-blocking comment before gating merges on propagation review.