Event Schema Coupling Analysis Prompt

This prompt is for platform engineers and architects who own event-driven systems and need to understand how producer schema changes will propagate to consumers. The core job-to-be-done is identifying hidden coupling between event schemas and downstream services before a breaking change reaches production. You should use this prompt when you are planning a schema evolution, auditing an existing event catalog for fragility, or onboarding a new team to your event backbone and need to map the blast radius of each schema.

The ideal user has access to a schema registry (e.g., Confluent Schema Registry, AWS Glue, or a git-based schema store), consumer code or subscription manifests, and a list of proposed or recent schema changes. The prompt requires grounding in real artifacts—it is not a thought experiment. You must provide the current schema, the proposed change, and a list of consumer schemas or at least consumer identifiers. Without these inputs, the model will hallucinate dependencies that don't exist. The prompt is designed for Avro, Protobuf, and JSON Schema, but works best when you specify the schema format explicitly.

Do not use this prompt for runtime debugging of deserialization errors, for performance analysis of serialization throughput, or for general API contract review outside of event-driven contexts. It is also not a replacement for schema compatibility checks built into your registry (e.g., Confluent's FULL_TRANSITIVE compatibility mode). The prompt adds value by analyzing semantic coupling—field-level dependencies that pass compatibility checks but still break consumer logic—which automated tools miss. Always pair the output with human review from the owning teams before blocking a deployment or forcing a migration.

The following prompt template is designed to be copied directly into your AI harness. It uses square-bracket placeholders for all dynamic inputs, ensuring you can swap in schema definitions, registry metadata, and output constraints without rewriting the core instruction. The template assumes you have access to producer and consumer schemas, a schema registry snapshot, and a list of known downstream consumers. If any of these are missing, the prompt will still produce a partial analysis but will flag gaps explicitly.

textCopy
You are a platform engineer reviewing event-driven architecture coupling. Your task is to produce a coupling report showing producer-consumer schema dependencies, field-level coupling, and breaking change propagation paths.

## INPUTS
- Producer Schema: [PRODUCER_SCHEMA]
- Consumer Schemas: [CONSUMER_SCHEMAS]
- Schema Registry Snapshot: [REGISTRY_SNAPSHOT]
- Known Downstream Consumers: [DOWNSTREAM_CONSUMERS]
- Change Context: [CHANGE_CONTEXT]

## OUTPUT SCHEMA
Return a JSON object with this exact structure:
{
  "producer": {
    "name": "string",
    "version": "string",
    "fields": [{"name": "string", "type": "string", "required": boolean}]
  },
  "consumers": [{
    "name": "string",
    "version": "string",
    "coupled_fields": [{"field": "string", "coupling_type": "direct|transitive|implicit", "usage_context": "string"}],
    "breaking_impact": "high|medium|low|none",
    "migration_effort": "string"
  }],
  "propagation_paths": [{
    "change": "string",
    "affected_consumers": ["string"],
    "cascade_depth": number,
    "risk_level": "high|medium|low"
  }],
  "registry_grounding": [{
    "schema_id": "string",
    "compatibility_mode": "string",
    "evolution_violations": ["string"]
  }],
  "unresolved_gaps": ["string"],
  "overall_risk": "high|medium|low"
}

## CONSTRAINTS
- Every coupled field must be traceable to a specific field in the producer schema.
- Every propagation path must reference at least one consumer from the consumer list.
- Registry grounding must cite actual schema IDs from the registry snapshot.
- If a consumer's usage context is unknown, mark coupling_type as "implicit" and add an entry to unresolved_gaps.
- Do not invent consumers, fields, or registry entries not present in the inputs.
- If the change context is empty, analyze all fields for potential breaking changes.

## RISK LEVEL: [RISK_LEVEL]
- If RISK_LEVEL is "high", require explicit human review before any schema evolution.
- If RISK_LEVEL is "medium", flag all medium and high propagation paths for review.
- If RISK_LEVEL is "low", still report all coupling but mark only high-impact paths for attention.

To adapt this template, replace each square-bracket placeholder with your actual data. For [PRODUCER_SCHEMA] and [CONSUMER_SCHEMAS], provide the full schema definitions in JSON Schema, Avro, or Protobuf format. For [REGISTRY_SNAPSHOT], include the schema registry's current state with compatibility modes and evolution history. For [DOWNSTREAM_CONSUMERS], list every known service, team, or application that consumes events from this producer. For [CHANGE_CONTEXT], describe the proposed schema change or leave it empty for a full baseline analysis. For [RISK_LEVEL], set the appropriate threshold based on your organization's change management policy. If you are integrating this into a CI/CD pipeline, wire the output JSON into a validation step that blocks deployments when overall_risk is "high" and no human approval has been recorded.

Before deploying this prompt, test it against at least three scenarios: a backward-compatible field addition, a breaking field removal, and a schema with missing consumer information. Validate that the output JSON conforms to the schema above and that every coupled_field references a real producer field. Common failure modes include hallucinated consumer names when the consumer list is incomplete, missing registry grounding when the snapshot is stale, and overly conservative risk ratings when the change context is vague. If you observe any of these, tighten the constraints section or add few-shot examples showing correct behavior for each scenario.

This prompt is designed to be integrated into a CI/CD pipeline or a pre-release review gate for event-driven systems. The primary integration point is a schema registry (such as Confluent Schema Registry, AWS Glue, or an internal protobuf/Avro repository) that serves as the source of truth. The harness must fetch the relevant schemas, format them into the [SCHEMA_DEFINITIONS] placeholder, and inject the specific [CHANGE_PROPOSAL] before calling the model. Because the output is a structured coupling report, the harness must validate the response against a strict JSON schema before accepting it. If the model returns a report with missing required fields (e.g., breaking_changes, affected_consumers, propagation_paths), the harness should retry with a repair prompt that includes the validation error, rather than silently accepting a malformed analysis.

Implement a three-stage pipeline: Fetch → Analyze → Validate. In the Fetch stage, query the schema registry for all subjects that reference the schema under review, resolving version histories and compatibility modes. In the Analyze stage, construct the prompt with the full schema definitions, the proposed change, and the required output schema. Use a model with strong structured output capabilities (GPT-4o or Claude 3.5 Sonnet with response_format set to json_schema) and set temperature=0 to minimize variance in the coupling analysis. In the Validate stage, check that every affected_consumer listed in the report maps to an actual schema registry subject fetched in the first stage—this prevents hallucinated consumers. For each breaking_change, verify that the field path exists in the current schema version. Log any validation failures as grounding_violations and surface them for human review. If the change proposal modifies a schema with BACKWARD compatibility mode, flag any report that claims zero breaking changes for manual inspection, as this is a common failure mode where the model underestimates impact.

For production use, wrap the entire harness in a retry loop with exponential backoff (max 3 attempts). On the first validation failure, append the specific schema errors to a repair prompt and re-invoke the model. On the second failure, escalate to a human review queue with the partial report and validation errors attached. Store every analysis result—including failed attempts—in an audit log keyed by schema version and change proposal ID. This audit trail is essential for governance reviews and for debugging model drift over time. Do not use this prompt for schemas with more than 50 fields or 20 downstream consumers in a single call; instead, split the analysis by consumer group and merge the results in the application layer. Finally, never allow the model's output to automatically block a schema registration or deployment—the coupling report is an advisory signal, and the final decision to proceed, warn, or block must remain with the platform team's policy engine.