Service Merge Candidate Identification Prompt

This prompt is designed for architects and engineering leads who are actively managing a system that has been over-decomposed into too many services. The primary job-to-be-done is to reverse 'nano-service sprawl' by identifying specific services that should be merged back together. You should use this prompt when your teams report that simple feature changes require coordinated pull requests across three or more services, when deployment synchronization meetings are a recurring calendar fixture, or when the cognitive load of tracking inter-service dependencies exceeds the value of independent deployability. The ideal user has access to a concrete service inventory, a dependency graph, and recent deployment history—this is not a greenfield design exercise.

Before running this prompt, you must assemble the required context: a list of services with their primary data stores, a mapping of shared database tables or event streams, and a record of coordinated deployments over the last quarter. The prompt analyzes coupling evidence, shared data ownership, coordinated deployment frequency, and cognitive load to produce a ranked merge candidate list. It will flag services that always change together, services that share a database despite being separate deployments, and services whose domain logic is so intertwined that separating them creates more problems than it solves. Do not use this prompt for greenfield service boundary design, for systems that are still largely monolithic, or when you lack empirical dependency data—the output will be speculative rather than evidence-based.

The output is a ranked list of merge candidates with specific evidence for each recommendation, estimated consolidation benefits, and a risk assessment for the merge operation. Use this as input to an architecture review meeting, not as a final decision. The prompt identifies candidates; your team must validate the findings against business context, team topology, and future roadmap. If the prompt returns an empty or low-confidence list, that is a valid signal that your current decomposition may be appropriate, and you should investigate whether coordination overhead stems from team structure rather than service boundaries.

This prompt is designed to be copied directly into your AI harness, IDE, or orchestration layer. It uses square-bracket placeholders for all dynamic inputs, ensuring you can adapt it to your specific system context without modifying the core instruction structure. The template expects a description of your current service landscape, coupling evidence, and any known pain points. Replace each placeholder with data from your architecture review, dependency graphs, or team surveys before sending the prompt to the model.

textCopy
You are a senior software architect specializing in microservice decomposition and consolidation. Your task is to analyze a potentially over-decomposed system and identify services that are strong candidates for merging.

## SYSTEM CONTEXT
[SYSTEM_DESCRIPTION]

## SERVICE INVENTORY
[SERVICE_LIST_WITH_RESPONSIBILITIES]

## COUPLING EVIDENCE
[COUPLING_DATA]

## DEPLOYMENT COORDINATION DATA
[DEPLOYMENT_FREQUENCY_AND_COORDINATION_PATTERNS]

## TEAM COGNITIVE LOAD ASSESSMENT
[TEAM_FEEDBACK_AND_COGNITIVE_LOAD_INDICATORS]

## CONSTRAINTS
[CONSTRAINTS]

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "merge_candidates": [
    {
      "services_to_merge": ["service-a", "service-b"],
      "merge_rationale": "string",
      "coupling_evidence": {
        "shared_data_ownership": ["entity-x", "entity-y"],
        "coordinated_deployment_frequency": "string",
        "chatty_communication_paths": ["path-1", "path-2"],
        "shared_business_capability": "string"
      },
      "cognitive_load_reduction_estimate": "high|medium|low",
      "merged_service_name_suggestion": "string",
      "merged_responsibility_statement": "string",
      "risk_assessment": {
        "migration_complexity": "high|medium|low",
        "rollback_safety": "high|medium|low",
        "team_impact": "string"
      },
      "nano_service_detection": {
        "is_nano_service": true|false,
        "nano_service_indicators": ["string"]
      }
    }
  ],
  "analysis_summary": "string",
  "recommended_merge_sequence": ["string"]
}

## INSTRUCTIONS
1. Review the service inventory and identify services that share the same data entities, require coordinated deployments, or exhibit excessive inter-service communication.
2. Flag any nano-services—services with a single responsibility that could be a module within a larger service.
3. For each merge candidate, provide specific coupling evidence and a clear rationale.
4. Estimate the cognitive load reduction for the owning team if the merge were completed.
5. Assess migration complexity and rollback safety for each candidate.
6. Recommend a merge sequence that minimizes blast radius and respects dependency ordering.
7. If no strong merge candidates exist, return an empty `merge_candidates` array and explain why in `analysis_summary`.

## RISK LEVEL
[RISK_LEVEL]

After copying the template, replace each placeholder with concrete data. For [SYSTEM_DESCRIPTION], include a brief overview of the system's domain and architecture style. [SERVICE_LIST_WITH_RESPONSIBILITIES] should be a structured list of service names and their stated responsibilities. [COUPLING_DATA] can include dependency graph outputs, shared database tables, or API call frequency metrics. [DEPLOYMENT_FREQUENCY_AND_COORDINATION_PATTERNS] should capture how often services are deployed together. [TEAM_FEEDBACK_AND_COGNITIVE_LOAD_INDICATORS] can include survey results or on-call rotation data. [CONSTRAINTS] should list any non-negotiable requirements, such as regulatory boundaries or team topology constraints. [RISK_LEVEL] should be set to high, medium, or low to calibrate the model's caution. For high-risk environments, always route the output through a human architecture review before any merge work begins. Validate the JSON output against the schema before processing downstream, and log the prompt version, inputs, and outputs for auditability.

This prompt is designed to operate as a structured analysis step within a broader architecture review workflow, not as a standalone chatbot interaction. The implementation harness should treat the prompt as a deterministic function: it receives a structured service inventory and returns a scored merge candidate list. Because the output directly influences refactoring decisions that carry operational risk, the harness must enforce validation, human review gates, and audit trail capture before any merge recommendation reaches an implementation backlog.

Wire the prompt into an application by first assembling the required inputs: a service inventory with ownership, data store mappings, deployment frequency, and dependency graph data. These inputs should be pulled from your service catalog, CI/CD pipelines, and infrastructure-as-code repositories rather than manually compiled. Before invoking the model, validate that the input payload conforms to the expected schema—missing fields like deployment_frequency or shared_data_stores will degrade the quality of coupling evidence. On invocation, use a model with strong structured output support (GPT-4o or Claude 3.5 Sonnet with JSON mode enabled) and set temperature to 0 or near-zero to maximize consistency across runs. Capture the raw model response, the validated merge candidate list, and the input snapshot in an audit log so that architecture decisions remain traceable.

Post-generation validation is critical. Implement a validator that checks each merge candidate for required fields: services_to_merge, coupling_evidence, shared_data_ownership, coordinated_deployment_frequency, and cognitive_load_reduction_estimate. Reject any candidate where the coupling evidence is purely syntactic (e.g., 'they share a name prefix') without concrete data or deployment coupling. Flag candidates where the cognitive load reduction estimate is implausible—merging two services with five engineers each should not claim a reduction to one engineer. If validation fails, retry once with the validation errors appended to the prompt as feedback. If the retry also fails, escalate the candidate to a human architect for manual review rather than silently accepting a weak recommendation.

The output should feed into a review queue, not directly into a refactoring backlog. Each merge candidate must be reviewed by at least one architect who can assess organizational context—team topology, Conway's Law alignment, and migration cost—that the model cannot see. The harness should present each candidate with its evidence, scores, and a link to the raw dependency data so reviewers can verify claims. After human approval, merge candidates can be promoted to implementation planning with a clear audit trail showing the model's recommendation, the validator's checks, and the human reviewer's sign-off. Avoid the temptation to automate the entire pipeline end-to-end; the cost of a bad merge far exceeds the cost of a human review step.