CQRS Read Model Design Prompt

This prompt is designed for architects and platform engineers who have drafted a read model schema and event subscription list and need a rigorous, pre-implementation review. The job-to-be-done is not to generate code, but to surface design risks that are easy to miss during whiteboard sessions: stale read windows, projection synchronization gaps, rebuild feasibility, and query performance bottlenecks. The ideal user understands CQRS fundamentals and can provide a concrete read model schema, the list of events it subscribes to, and the intended query patterns. The prompt acts as a second pair of eyes, systematically evaluating the design against known failure modes in eventually-consistent systems.

You should run this prompt after the team has aligned on the read model's purpose and shape but before any projection handler code is written. Required inputs include the read model's target schema (fields, types, and keys), the list of source events with their schemas, the expected query load and latency requirements, and the planned rebuild strategy (e.g., full replay from event store, snapshot-based, or hybrid). The prompt assumes the event store and write-side model are already defined; it does not review the command side. Do not use this prompt for simple CRUD views that don't involve event projection, or for systems where strong consistency is required and eventual consistency is unacceptable.

The prompt's value lies in its structured output: it produces a review covering projection logic gaps, eventual consistency window analysis, rebuild strategy feasibility, and query performance risks. It also includes explicit eval checks for stale read risk and synchronization gaps. After receiving the output, the team should walk through each identified risk, decide which require design changes, and document the accepted trade-offs in an architecture decision record. Avoid using this prompt as a one-time gate; re-run it when the event schema evolves or new query patterns are introduced, as these changes often invalidate prior assumptions about consistency and performance.

The following prompt template is designed to be pasted directly into your AI workspace. It instructs the model to act as a systems architect conducting a rigorous review of a CQRS read model design. The prompt is structured to produce a consistent, actionable output by focusing on the four critical areas of read model risk: projection logic, eventual consistency, rebuild feasibility, and query performance. Replace every square-bracket placeholder with the specific details of your system before execution.

textCopy
You are a systems architect specializing in CQRS and event-driven architectures. Your task is to review a read model design for correctness, resilience, and performance. You will produce a structured review report.

## SYSTEM CONTEXT
[SYSTEM_DESCRIPTION: A brief overview of the system and the bounded context this read model belongs to.]

## READ MODEL DEFINITION
- **Name:** [READ_MODEL_NAME]
- **Purpose:** [QUERY_USE_CASE: The specific query or UI view this model supports.]
- **Source Events:** [LIST_OF_SOURCE_EVENTS: The domain events that trigger updates to this read model.]
- **Projection Logic:** [PROJECTION_LOGIC_DESCRIPTION: How events are transformed into the read model state. Include aggregation, filtering, and joining logic.]
- **Target Data Store:** [DATABASE_TYPE: e.g., PostgreSQL, Elasticsearch, Redis, DynamoDB]
- **Target Schema:** [OUTPUT_SCHEMA: The final shape of the read model data, including fields and types.]

## CONSTRAINTS
[CONSTRAINTS: Specific non-functional requirements like max query latency, data freshness SLA (e.g., < 5 seconds), and consistency guarantees.]

## OUTPUT FORMAT
Generate a review report with the following sections:
1.  **Projection Design Review:** Analyze the projection logic for correctness, idempotency, and handling of out-of-order events. Identify any missing state transitions.
2.  **Eventual Consistency Assessment:** Quantify the expected consistency window. Identify scenarios where stale reads could cause user-facing errors or incorrect business logic.
3.  **Rebuild Strategy Audit:** Evaluate the feasibility of a full historical rebuild. Identify missing event history, snapshot dependencies, and time-to-rebuild estimates.
4.  **Query Performance Analysis:** Review the target schema and data store choice against the query use case. Flag potential performance bottlenecks like missing indexes, hot partitions, or N+1 query patterns.
5.  **Risk Register:** A table of identified risks, each with a severity (High/Medium/Low), a description, and a recommended mitigation.

## EVALUATION CRITERIA
A successful review will:
- Explicitly state the assumptions made about event ordering and delivery guarantees.
- Flag any projection logic that is not idempotent.
- Provide a concrete, testable scenario for a stale read risk.
- Identify if the rebuild strategy relies on event streams with a limited retention period.

To adapt this prompt, start by filling in the [SYSTEM_DESCRIPTION] and [READ_MODEL_NAME] to ground the model. The most critical placeholders are [PROJECTION_LOGIC_DESCRIPTION] and [CONSTRAINTS]. Be precise about the projection logic, as this is where subtle bugs like missed state transitions or non-idempotent operations hide. For constraints, specify a concrete data freshness SLA (e.g., 'read model must reflect state no more than 2 seconds behind the write model') to force a quantitative consistency assessment. After receiving the output, you should manually verify the identified stale read scenarios against your actual event flow latency to confirm the model's analysis is grounded in your production reality.

This prompt is designed to operate as a gated review step within a broader architecture workflow, not as a standalone chatbot interaction. The implementation harness should treat the prompt output as a structured artifact that requires validation before it enters your decision log. The core integration pattern is: collect the read model specification from the architect, assemble the prompt with the specification and any relevant event schema context, submit to the model, validate the output against the expected schema, and route the result to a human reviewer for final sign-off before filing it as an architecture decision record.

Validation and retry logic is critical because this prompt operates in a domain where stale reads and projection gaps can cause data corruption in production. Implement a schema validator that checks the output JSON for required fields: projection_risks, consistency_window_assessment, rebuild_feasibility, and query_performance_notes. If validation fails, retry once with the error message appended to the prompt context. If the retry also fails, escalate to a human reviewer with the partial output and validation errors logged. For model choice, prefer a model with strong reasoning capabilities and long context windows, as read model reviews often require reasoning across multiple event types and projection logic simultaneously. Claude 3.5 Sonnet or GPT-4o are suitable defaults; avoid smaller models that may drop structural fields under complex constraints.

Logging and observability should capture the full prompt, the raw model output, the validated output, and the human review decision. Store these in a review log that can be referenced during incident postmortems if a read model failure occurs in production. Include the model version, timestamp, and retry count in the log. For teams using RAG, you can augment the prompt with relevant event schema definitions and existing read model documentation retrieved from your architecture repository, but ensure the retrieved context is clearly separated from the architect's new specification to avoid conflation. The human approval gate is mandatory for any read model that serves customer-facing queries or financial reconciliation workflows; automated approval is acceptable only for internal operational read models with low staleness tolerance. The next step after approval is to file the validated review alongside the read model implementation plan and link both to the parent CQRS design document.