Pub-Sub Topology Evaluation Prompt

This prompt is for architects and platform engineers who need to review a publish-subscribe topology before it reaches production. It takes a topology specification as input and produces a structured assessment identifying fan-out risks, coupling points, orphaned subscribers, circular event flows, and dead letter routing gaps. Use this prompt during architecture review gates, pre-implementation design sessions, or when onboarding new services into an existing event-driven system. The output is designed to be actionable: each finding includes a severity rating and a concrete recommendation.

Do not use this prompt for runtime debugging of a live system or for reviewing code-level implementation details. It belongs in the design review phase, before code is written. The prompt expects a topology specification that includes publishers, subscribers, topics, queues, routing rules, and dead letter configurations. If you only have a partial topology or a single service's event bindings, this prompt will produce incomplete results. Pair this prompt with the Event-Driven Anti-Pattern Detection Prompt for a broader design review, or with the Dead Letter Queue Design Prompt when DLQ gaps are the primary concern.

The ideal user is someone who can authoritatively describe the topology and act on the findings. This is typically a staff engineer, solution architect, or platform team lead. The prompt assumes the reviewer understands event-driven patterns and can interpret coupling and fan-out assessments. If the reviewer is new to pub-sub architectures, supplement the output with the Event-Driven System Failure Mode Analysis Prompt to build intuition about what breaks first in production. After running this prompt, feed the findings into your architecture decision record process and use the severity ratings to prioritize remediation before implementation begins.

The prompt below is designed to be dropped directly into your AI-assisted architecture review workflow. It instructs the model to act as a distributed systems reviewer and systematically assess a publish-subscribe topology specification. The template uses square-bracket placeholders that you must replace with your actual topology description, the specific risks you want to surface, and the output format your downstream tooling expects. Do not leave any placeholder unresolved when you send the prompt to the model.

textCopy
You are a distributed systems architect reviewing a publish-subscribe topology. Your task is to produce a structured topology assessment that identifies risks, coupling points, and operational gaps.

## Topology Specification
[TOPOLOGY_SPECIFICATION]

## Review Constraints
Focus your analysis on the following specific risk areas:
[RISK_AREAS]

## Output Schema
Return your assessment as a valid JSON object conforming to this structure:
{
  "topology_summary": "A concise description of the topology's purpose and primary data flows.",
  "fan_out_risks": [
    {
      "topic_or_exchange": "string",
      "subscriber_count": "number",
      "risk_description": "string",
      "severity": "high|medium|low",
      "mitigation": "string"
    }
  ],
  "coupling_points": [
    {
      "location": "string",
      "coupling_type": "temporal|schema|routing|infrastructure",
      "description": "string",
      "impact": "string"
    }
  ],
  "dead_letter_routing_gaps": [
    {
      "queue_or_subscriber": "string",
      "gap_description": "string",
      "recommendation": "string"
    }
  ],
  "orphaned_subscribers": [
    {
      "subscriber": "string",
      "evidence": "string"
    }
  ],
  "circular_event_flows": [
    {
      "cycle": ["string"],
      "risk": "string"
    }
  ],
  "overall_risk_score": "high|medium|low",
  "critical_recommendations": ["string"]
}

## Instructions
- If the topology specification is incomplete, note missing information in the `topology_summary` field and proceed with the available data.
- For every risk identified, provide a concrete, actionable mitigation.
- Flag any subscriber that appears to have no corresponding publisher as an orphaned subscriber.
- Detect circular event flows where a published event can trigger a chain that leads back to the original publisher.
- If no issues are found in a category, return an empty array for that field.
- Do not invent topology details not present in the specification.

After pasting the template, replace [TOPOLOGY_SPECIFICATION] with a detailed description of your pub-sub system. This should include topic or exchange names, subscriber lists, message schemas, routing keys, queue bindings, and any dead letter queue configuration. For [RISK_AREAS], list the specific failure modes you are most concerned about, such as "fan-out saturation under peak load," "tight temporal coupling between OrderService and PaymentService," or "missing DLQ for fraud detection events." If you are integrating this prompt into an automated pipeline, ensure the JSON output is validated against the schema before it is stored in your architecture decision log. For high-severity findings, route the output for human review before accepting the assessment.

This prompt is designed to be integrated into a pre-merge architecture review pipeline, not run as a one-off chat. The primary integration point is a pull request or design document review where a proposed pub-sub topology diagram (in Mermaid, PlantUML, or structured JSON) is submitted alongside a context document describing the system's non-functional requirements. The harness should extract the topology specification and context, inject them into the prompt's [TOPOLOGY_SPEC] and [CONTEXT] placeholders, and route the output to a structured review comment on the PR. Because the prompt identifies high-severity risks like orphaned subscribers and circular event flows, the harness must treat a risk_level: critical finding as a blocking review, not a suggestion.

The implementation should wrap the LLM call in a validation layer that parses the expected JSON output schema before posting results. If the model returns malformed JSON or missing required fields (topology_id, risks, coupling_points), the harness should retry once with a stricter repair prompt that includes the raw output and a request to fix the schema. After two failures, the harness must escalate to a human reviewer via a labeled comment (e.g., ⚠️ topology-eval-bot failed to produce valid output). For model choice, use a model with strong structured output support and a context window large enough to hold the full topology spec plus evaluation criteria—GPT-4o or Claude 3.5 Sonnet are appropriate defaults. Set temperature=0 to maximize deterministic, repeatable evaluations across PR revisions.

Log every evaluation run as an audit event: capture the topology spec hash, the prompt version, the model identifier, the raw and parsed outputs, and the review decision (approved, changes requested, or escalated). This log becomes evidence for governance reviews and helps debug false positives when the prompt flags a pattern that is intentional. Do not cache evaluations across topology changes—a single subscriber addition can invalidate a prior clean assessment. Finally, pair this prompt with a human-in-the-loop rule: any risk_level: critical finding must be acknowledged by an architect before the PR can merge, even if the bot's comment is the only blocker.