Distributed Monolith Risk Detection Prompt

Use this prompt when you are an architect or technical lead reviewing a microservice decomposition plan, a migration roadmap, or an existing distributed system that feels harder to change than it should. The job-to-be-done is detecting distributed monolith smells—tight coupling, shared databases, chatty communication, and synchronous chains—before they calcify into an operational and delivery bottleneck. You need a structured risk register, not a generic opinion, and you need it grounded in the specific architecture artifacts you provide: service maps, data ownership matrices, API contracts, or deployment diagrams.

The prompt is designed for a reader who already understands distributed systems trade-offs and needs a rigorous, evidence-based review. You must supply concrete context: a list of services, their dependencies, data store assignments, communication protocols, and any known pain points. The prompt works best when you include both the intended design and the actual implementation reality, because the gap between them is where distributed monoliths hide. Do not use this prompt for greenfield system design, for evaluating a monolith that has not yet been decomposed, or for performance profiling—those require different prompts focused on design generation, monolith analysis, or load testing respectively.

Before running this prompt, gather your architecture evidence. If you lack a dependency graph or data ownership map, start with the Service Dependency Graph Coupling Score Prompt or the Cross-Service Data Ownership Analysis Prompt first. After you receive the risk register, use the remediation sequencing guidance to prioritize fixes, then feed the highest-risk items into the Service Boundary Candidate Identification Prompt or the Strangler Fig Migration Step Planning Prompt. Do not treat the output as a final verdict—validate each finding against your team's operational experience and use the risk register as a discussion artifact for an architecture review session with the full engineering team.

This prompt template is designed to be copied directly into your AI harness, IDE, or orchestration layer. It accepts a system description, architecture artifacts, and evaluation constraints, then produces a structured risk register. Every placeholder is enclosed in square brackets and must be replaced with concrete values before execution. The template assumes you have already gathered the necessary context—deployment diagrams, service inventories, database schemas, and communication patterns—and are ready to run a structured risk assessment.

textCopy
You are an experienced distributed systems architect reviewing a microservice decomposition plan or existing system for distributed monolith smells. Your goal is to produce a structured risk register that identifies coupling patterns, shared dependencies, and communication anti-patterns that would negate the benefits of a service-oriented architecture.

## INPUT
[SYSTEM_DESCRIPTION]
[ARCHITECTURE_DIAGRAMS_OR_ARTIFACTS]
[SERVICE_INVENTORY]
[DATABASE_SCHEMAS_OR_DATA_STORE_DESCRIPTIONS]
[COMMUNICATION_PATTERNS_AND_PROTOCOLS]

## OUTPUT_SCHEMA
Return a valid JSON object with this exact structure:
{
  "assessment_summary": "string (2-3 sentence executive summary)",
  "risk_register": [
    {
      "risk_id": "string (unique identifier, e.g., DM-001)",
      "risk_category": "string (one of: SharedDatabase, ChattyCommunication, TightCoupling, SynchronousChain, DataOwnershipViolation, DeploymentCoupling, SchemaCoupling, IdentityCoupling, DistributedTransaction, ObservabilityGap)",
      "severity": "string (Critical | High | Medium | Low)",
      "affected_services": ["string"],
      "description": "string (specific pattern observed and why it's problematic)",
      "evidence": "string (concrete reference to the input artifacts that demonstrates this risk)",
      "remediation": "string (specific, actionable recommendation)",
      "remediation_effort": "string (Small | Medium | Large | X-Large)",
      "remediation_sequencing_priority": "integer (1 = address first, higher numbers = later)"
    }
  ],
  "coupling_heatmap": {
    "service_pairs": [
      {
        "service_a": "string",
        "service_b": "string",
        "coupling_score": "number (0-100, where 100 is maximum coupling)",
        "primary_concern": "string"
      }
    ]
  },
  "remediation_roadmap": {
    "phases": [
      {
        "phase": "integer",
        "objective": "string",
        "risks_addressed": ["string (risk_ids)"],
        "estimated_effort": "string",
        "success_criteria": "string"
      }
    ]
  },
  "false_positive_notes": ["string (any patterns that look risky but are justified in this context)"]
}

## CONSTRAINTS
- Only flag risks that are supported by evidence in the provided artifacts. Do not speculate about risks that might exist in a different system.
- If a shared database is justified by low-latency transactional requirements and the services are owned by the same team, note this in false_positive_notes rather than flagging it as Critical.
- Distinguish between synchronous chains that are architecturally necessary (e.g., authentication) and those that are accidental coupling.
- For each risk, the remediation must be specific to the affected services, not generic advice.
- If the input is incomplete or ambiguous, list what additional information would be needed in a separate "information_gaps" field at the top level of the output.

## RISK_LEVEL
[HIGH] This assessment may influence architecture decisions, extraction sequencing, and team assignments. Flag uncertainty explicitly. Do not present speculation as certainty.

## EXAMPLES
[OPTIONAL_FEW_SHOT_EXAMPLES]

To adapt this template, start by replacing [SYSTEM_DESCRIPTION] with a concise narrative of what the system does and its current architectural state. The [ARCHITECTURE_DIAGRAMS_OR_ARTIFACTS] placeholder should contain textual descriptions of deployment diagrams, sequence diagrams, or dependency graphs—if you have actual diagrams, describe them in prose. [SERVICE_INVENTORY] expects a list of services with their responsibilities, while [DATABASE_SCHEMAS_OR_DATA_STORE_DESCRIPTIONS] should describe which services access which data stores and whether any databases are shared. For [COMMUNICATION_PATTERNS_AND_PROTOCOLS], describe whether services communicate via synchronous HTTP, gRPC, asynchronous messaging, or shared databases. The [OPTIONAL_FEW_SHOT_EXAMPLES] placeholder can be populated with 1-2 example risk entries that demonstrate your expected severity calibration and evidence style. If you are assessing a proposed design rather than an existing system, add a [DESIGN_STAGE] field set to "proposed" so the model adjusts its certainty language accordingly.

Before using this prompt in production, validate that the output JSON conforms to the schema using a JSON Schema validator. Pay particular attention to the risk_category enum—if the model introduces a new category, either update the schema or add a post-processing step to map it to an allowed value. For high-stakes architecture reviews, run this prompt against multiple models and compare the risk registers for consensus. Disagreements between models on severity or risk presence are themselves useful signals that warrant human architect review. Never treat the output as a final decision; it is a structured input to an architecture review meeting where experienced engineers validate findings against operational reality.

This prompt is designed to operate as a batch analysis step inside an architecture review workflow, not as a real-time chat interaction. The typical integration pattern is: collect system artifacts (deployment diagrams, service dependency graphs, database schemas, API specifications, and communication traces), assemble them into the [SYSTEM_ARTIFACTS] placeholder, and submit the prompt through an API call to a model capable of structured output. The output is a risk register JSON object that downstream tooling can parse, store, and display. Because the analysis covers architectural decisions that may influence refactoring roadmaps and resource allocation, the harness must include validation, retry logic, and a human review step before any findings are treated as actionable.

Validation and retry strategy. The prompt requests a specific JSON schema with risks, coupling_patterns, shared_database_dependencies, chatty_communication_paths, and remediation_sequence fields. Implement a schema validator that checks the response against this contract immediately after the model returns. If validation fails, retry up to two times with the same prompt, appending the validation error to the [CONSTRAINTS] section as a correction instruction. After three failed attempts, log the failure, capture the raw response for debugging, and escalate to a human reviewer rather than silently accepting a malformed output. For high-stakes reviews, add a confidence threshold check: if the model includes a confidence field below 0.7 for any individual risk item, flag that item for mandatory human review even if the schema is valid.

Model selection and tool use. This prompt benefits from models with strong reasoning capabilities and large context windows, as system artifacts can be extensive. GPT-4o, Claude 3.5 Sonnet, and Gemini 1.5 Pro are suitable starting points. The prompt does not require function calling or external tools during execution, but you may choose to wire it into a RAG pipeline if your system artifacts are stored in a documentation repository. In that case, retrieve relevant architecture decision records, dependency graphs, and database schemas before assembling the prompt, and include source references in the [SYSTEM_ARTIFACTS] section so the model can cite specific documents in its findings.

Human review and downstream integration. Every risk item in the output should be surfaced in a review UI that allows an architect to accept, reject, or annotate each finding. Store the raw model output, the reviewer's decisions, and the final approved risk register in a versioned artifact store. This creates an audit trail for governance and allows you to measure the prompt's precision and recall over time. Avoid wiring the output directly into automated refactoring tools or ticket creation systems without human approval—the cost of acting on a false positive (e.g., splitting a service that should remain together) is high. The remediation_sequence field provides a suggested ordering, but sequencing decisions should always be reviewed against team capacity, business priorities, and operational constraints that the model cannot fully assess.