Event Sourcing Schema Review Prompt

This prompt is for architects and platform engineers who need a structured, automated first pass at reviewing event-sourced aggregate schemas. The job-to-be-done is catching design flaws—such as incorrect event granularity, missing snapshot strategies, or projection rebuild feasibility gaps—before the schema is committed and events are produced. The ideal user has a draft aggregate schema and a set of event type definitions, and they need a review that goes beyond linting to assess runtime behavior, evolution risk, and operational recoverability. You should use this prompt when a new aggregate is being designed, when an existing aggregate is undergoing a significant schema change, or as a gate in a CI/CD pipeline for event schema registries.

Do not use this prompt for reviewing individual event schemas in isolation (use the Event Schema Design Review Prompt Template instead), for runtime debugging of event processing failures, or for systems that do not use event sourcing. The prompt assumes the reader understands Domain-Driven Design aggregates, event versioning, and projection rebuilds. It is not a tutorial. The required inputs are the aggregate definition, its event type taxonomy, the current snapshot strategy, and any known projection dependencies. The output is a structured review covering event granularity, snapshot strategy, event type taxonomy, and projection rebuild feasibility, with explicit failure mode checks for event splitting and type explosion. Because aggregate schema decisions have long-lived production consequences—incorrect granularity can force expensive event migrations and type explosion can degrade projection performance—this prompt includes mandatory eval criteria and recommends human review for any findings flagged as high risk before the schema is finalized.

After running the review, treat the output as a design discussion artifact, not a final verdict. Validate each finding against your system's specific latency, storage, and consistency requirements. Pay particular attention to the failure mode checks: event splitting (where a single business event is incorrectly decomposed into multiple fine-grained events, breaking atomicity) and type explosion (where unbounded event type proliferation makes projection code unmaintainable). If the prompt flags either of these, schedule a synchronous design review with the team before proceeding. For high-risk domains such as finance or healthcare, always require human sign-off on the review output before schema registration.

This prompt template is designed to be copied directly into your AI harness or development environment. It uses square-bracket placeholders that you must replace with your specific domain context, event schemas, and review constraints. The template is structured to produce a consistent, actionable schema review that covers event granularity, snapshot strategy, event type taxonomy, and projection rebuild feasibility. Before using this prompt in production, ensure you have defined your evaluation criteria and failure mode checks as described in the implementation harness section.

textCopy
You are an expert software architect specializing in event sourcing and domain-driven design. Your task is to review an event-sourced aggregate schema for correctness, evolvability, and operational feasibility.

## INPUT

### Aggregate Context
- Aggregate Name: [AGGREGATE_NAME]
- Bounded Context: [BOUNDED_CONTEXT]
- Business Domain: [BUSINESS_DOMAIN]
- Aggregate Purpose: [AGGREGATE_PURPOSE_DESCRIPTION]

### Event Schema
[EVENT_SCHEMA_DEFINITIONS]

### Snapshot Configuration
- Snapshot Frequency: [SNAPSHOT_FREQUENCY]
- Snapshot Strategy: [SNAPSHOT_STRATEGY]
- Current Snapshot Schema: [SNAPSHOT_SCHEMA]

### Projection Requirements
[PROJECTION_REQUIREMENTS]

## CONSTRAINTS
- [CONSTRAINT_1]
- [CONSTRAINT_2]
- [CONSTRAINT_3]

## OUTPUT_SCHEMA
Produce a structured review with the following sections. Use the exact field names and types specified.

{
  "review_summary": {
    "overall_assessment": "string (PASS | PASS_WITH_RECOMMENDATIONS | FAIL)",
    "critical_issues_count": "integer",
    "recommendations_count": "integer"
  },
  "event_granularity_analysis": {
    "assessment": "string",
    "issues": [
      {
        "event_name": "string",
        "issue_type": "string (TOO_COARSE | TOO_FINE | AMBIGUOUS_BOUNDARY)",
        "description": "string",
        "recommendation": "string"
      }
    ],
    "suggested_splits": [
      {
        "original_event": "string",
        "proposed_events": ["string"],
        "rationale": "string"
      }
    ],
    "suggested_merges": [
      {
        "original_events": ["string"],
        "proposed_event": "string",
        "rationale": "string"
      }
    ]
  },
  "event_type_taxonomy_review": {
    "assessment": "string",
    "taxonomy_gaps": ["string"],
    "naming_consistency_issues": [
      {
        "event_name": "string",
        "issue": "string",
        "suggested_name": "string"
      }
    ],
    "missing_event_types": [
      {
        "event_type": "string",
        "rationale": "string",
        "suggested_schema": "object"
      }
    ],
    "type_explosion_risk": "string (LOW | MEDIUM | HIGH)",
    "type_explosion_mitigation": "string"
  },
  "snapshot_strategy_review": {
    "assessment": "string",
    "frequency_appropriateness": "string (APPROPRIATE | TOO_FREQUENT | TOO_INFREQUENT)",
    "schema_alignment_issues": ["string"],
    "performance_considerations": "string",
    "recommended_changes": ["string"]
  },
  "projection_rebuild_feasibility": {
    "assessment": "string",
    "rebuild_complexity": "string (LOW | MEDIUM | HIGH | NOT_FEASIBLE)",
    "blocking_factors": ["string"],
    "estimated_rebuild_concerns": "string",
    "recommended_improvements": ["string"]
  },
  "failure_mode_analysis": {
    "event_splitting_risks": [
      {
        "scenario": "string",
        "impact": "string",
        "detection_strategy": "string",
        "mitigation": "string"
      }
    ],
    "type_explosion_risks": [
      {
        "scenario": "string",
        "impact": "string",
        "detection_strategy": "string",
        "mitigation": "string"
      }
    ],
    "schema_evolution_risks": [
      {
        "change_type": "string",
        "breaking_change": "boolean",
        "impact": "string",
        "migration_strategy": "string"
      }
    ]
  },
  "action_items": [
    {
      "priority": "string (CRITICAL | HIGH | MEDIUM | LOW)",
      "category": "string",
      "description": "string",
      "effort_estimate": "string",
      "blocking_deployment": "boolean"
    }
  ]
}

## INSTRUCTIONS
1. Analyze each event in the schema for appropriate granularity. Events should represent meaningful business state changes, not CRUD operations or technical implementation details.
2. Review the event type taxonomy for completeness, consistency, and risk of type explosion. Flag any events that should be split, merged, or renamed.
3. Evaluate the snapshot strategy against the aggregate's event volume, performance requirements, and rebuild needs.
4. Assess whether all required projections can be rebuilt from the event stream. Identify any missing event data that would block rebuilds.
5. Perform a failure mode analysis covering event splitting risks, type explosion scenarios, and schema evolution breaking changes.
6. For every issue identified, provide a concrete, actionable recommendation.
7. If the schema has critical flaws that would cause data loss or unrecoverable state, mark the overall assessment as FAIL.

## RISK_LEVEL
[RISK_LEVEL]

If RISK_LEVEL is HIGH, flag any recommendation that could cause data loss or production incidents and require explicit human approval before implementation.

To adapt this template for your specific use case, replace each square-bracket placeholder with your actual domain data. The [EVENT_SCHEMA_DEFINITIONS] placeholder should contain your complete event schema in a structured format such as JSON Schema, Avro, or Protobuf definitions. The [PROJECTION_REQUIREMENTS] placeholder should describe each read model or projection that must be rebuildable from the event stream, including the fields required and any performance constraints. The [CONSTRAINT_1] through [CONSTRAINT_3] placeholders allow you to inject domain-specific rules such as regulatory requirements, latency budgets, or team capability constraints. The [RISK_LEVEL] placeholder should be set to LOW, MEDIUM, or HIGH based on the criticality of the system under review. For high-risk systems such as financial ledgers or healthcare records, the prompt will enforce additional caution in its recommendations and require explicit human approval gates. After adapting the template, validate the output against the evaluation criteria defined in your test harness before integrating it into your review pipeline.

This prompt is designed to operate as a gated step in a schema review pipeline, not as a standalone chatbot interaction. The harness wraps the LLM call with pre-processing to extract and normalize the event schema from design documents, post-processing to validate the output against a strict JSON schema, and conditional routing to human review when confidence is low or critical failure modes are flagged. The goal is to produce a machine-readable review artifact that downstream tooling can consume for trend analysis, regression checks, and audit evidence.

Input assembly begins by extracting the event schema from the user's design document. Use a lightweight extraction step (a smaller, cheaper model or a deterministic parser) to isolate the schema definition, event type taxonomy, snapshot configuration, and projection specifications. Feed these into the prompt's [EVENT_SCHEMA] and [CONTEXT] placeholders. Set [REVIEW_DEPTH] to comprehensive for new schemas or incremental for schema changes. The [OUTPUT_SCHEMA] placeholder should contain the expected JSON structure: an object with review_summary, event_granularity_assessment, snapshot_strategy_review, event_type_taxonomy_review, projection_rebuild_feasibility, failure_mode_checks (including event splitting and type explosion flags), and a risk_level enum of low, medium, or high.

Validation and retry logic is critical because malformed output breaks downstream automation. After the LLM responds, validate the JSON against the expected schema. If validation fails, retry up to two times with the error message appended to the prompt as a correction hint. If the output still fails validation, route to a human reviewer with the raw output and validation errors. For successful parses, check the risk_level field: high always triggers human review; medium triggers review if any failure_mode_checks flag is true; low can auto-approve unless the projection_rebuild_feasibility field indicates rebuild time exceeds a configurable threshold (e.g., >4 hours). Log every review result with the schema version, timestamp, model used, retry count, and final disposition for audit trails.

Model choice and tool integration depend on your risk tolerance. Use a capable reasoning model (GPT-4o, Claude 3.5 Sonnet, or equivalent) for the review itself. For the extraction step, a smaller model like GPT-4o-mini or Claude Haiku is sufficient. If your event schemas are stored in a schema registry (e.g., Apicurio, Confluent), integrate a tool that fetches the current schema version and any prior review artifacts as additional context. This enables the prompt to perform change-impact analysis by comparing the new schema against the prior version. For teams using event sourcing frameworks like Marten or Axon, add a post-review tool that writes the review artifact back to the schema registry as metadata, creating a permanent link between the schema and its architectural assessment.

Human approval gates should be implemented as a review queue, not an email. When the harness routes a review for human approval, present the reviewer with the original schema, the LLM's structured review, the specific failure flags that triggered escalation, and a one-click approve/reject interface. Rejection should require a reason, which feeds back into the prompt as a correction example for future runs. This closed loop improves the prompt's accuracy over time without manual prompt engineering. Avoid deploying this harness without the human gate for schemas that affect financial events, compliance data, or projections that serve customer-facing read models—silent schema errors in event-sourced systems can corrupt historical state in ways that are expensive to repair.