Service Dependency Graph Coupling Score Prompt

Use this prompt when you have a known service dependency graph—represented as a list of nodes and directed edges—and need a quantitative coupling analysis to inform architectural decisions. The ideal user is a platform engineer, architect, or technical lead preparing for a monolith extraction, microservice consolidation, or dependency modernization effort. You must already have the dependency graph available, typically derived from service meshes, API gateways, static analysis tools, or architecture documentation. The prompt computes afferent coupling (Ca), efferent coupling (Ce), instability (I = Ce / (Ca + Ce)), and ranks services by change propagation risk. It also detects cyclic dependencies and flags services that exceed configurable coupling thresholds.

This is a design-level analysis prompt, not a runtime observability tool. It assumes the dependency graph is accurate and complete at the time of analysis. The output includes a ranked risk table, cyclic dependency detection, and threshold alerts that can feed directly into an architecture decision record or migration sequencing plan. You can configure the instability threshold, maximum acceptable cycle length, and the minimum dependency count that triggers a warning. The prompt works best when paired with a structured input format—typically JSON or YAML representing nodes, edges, and optional metadata like protocol type or criticality labels. For high-stakes refactoring decisions, always validate the output against your own architecture knowledge and consider a human architecture review before acting on the rankings.

Do not use this prompt when you need real-time traffic analysis, runtime latency data, infrastructure-level network topology, or dynamic dependency discovery. It is not a substitute for a full architecture review—it quantifies coupling, not correctness, and cannot assess whether a dependency is semantically appropriate. If your dependency graph is incomplete or inferred from unreliable sources, the coupling scores will be misleading. For systems with asynchronous, event-driven dependencies, ensure those indirect couplings are represented as edges in the input graph, or the analysis will miss hidden propagation paths. After running this analysis, the natural next step is to feed the ranked risk list into a service extraction candidate scoring prompt or a change propagation risk analysis prompt to build a sequenced migration plan.

This prompt template is designed to be pasted directly into your AI workflow. It accepts a structured representation of your service dependency graph and returns a quantitative coupling analysis. The template uses square-bracket placeholders that you must replace with your actual data before sending. The output includes afferent/efferent coupling scores, instability metrics, and a prioritized list of services that pose the highest change propagation risk. This is not a conversational prompt—it expects structured input and returns structured output suitable for parsing into dashboards, architecture decision records, or CI/CD fitness functions.

textCopy
You are a platform architecture analyst evaluating a service dependency graph for coupling risk. Your task is to compute coupling scores, instability metrics, and change propagation risk rankings from the provided graph.

## INPUT
[DEPENDENCY_GRAPH]

## DEFINITIONS
- **Afferent Coupling (Ca):** Number of services that depend on this service (incoming dependencies).
- **Efferent Coupling (Ce):** Number of services this service depends on (outgoing dependencies).
- **Instability (I):** I = Ce / (Ca + Ce). Range 0.0 (stable, many dependents) to 1.0 (unstable, depends on many others).
- **Cyclic Dependency:** A path where a service transitively depends on itself (A→B→C→A).

## OUTPUT_SCHEMA
Return a JSON object with the following structure:
{
  "services": [
    {
      "name": "string",
      "afferent_coupling": number,
      "efferent_coupling": number,
      "instability": number,
      "dependents": ["string"],
      "dependencies": ["string"],
      "cyclic_dependency_risk": "none" | "direct" | "transitive",
      "change_propagation_risk": "low" | "medium" | "high" | "critical"
    }
  ],
  "cycles_detected": [
    {
      "cycle": ["string"],
      "severity": "warning" | "critical"
    }
  ],
  "ranked_by_risk": ["string"],
  "summary": {
    "total_services": number,
    "average_instability": number,
    "cyclic_dependency_count": number,
    "highest_risk_service": "string"
  }
}

## CONSTRAINTS
- Compute Ca and Ce from the provided graph only. Do not infer dependencies not present.
- Instability must be calculated as Ce / (Ca + Ce). If Ca + Ce = 0, set instability to 0.0 and flag the service as isolated.
- Change propagation risk is derived from: instability score, number of dependents, and presence of cyclic dependencies. Use this mapping:
  - Critical: instability > 0.8 AND dependents > 3, OR part of a critical cycle.
  - High: instability > 0.7 OR part of a warning cycle.
  - Medium: instability between 0.3 and 0.7.
  - Low: instability < 0.3.
- Detect both direct cycles (A→B→A) and transitive cycles (A→B→C→A).
- Rank services by change propagation risk (critical first, then high, medium, low).
- If the input is malformed or missing dependency information, return an error object: {"error": "string", "detail": "string"}.

## EXAMPLE_INPUT_FORMAT
The [DEPENDENCY_GRAPH] will be provided as a JSON adjacency list:
{
  "service-a": ["service-b", "service-c"],
  "service-b": ["service-c"],
  "service-c": ["service-a"],
  "service-d": []
}

## RISK_LEVEL
This analysis informs architectural decisions about service decomposition, migration sequencing, and integration testing scope. Outputs should be reviewed by a senior engineer or architect before driving refactoring priorities. Cyclic dependencies flagged as critical require immediate attention.

To adapt this prompt for your environment, replace [DEPENDENCY_GRAPH] with your actual service dependency data in the adjacency list format shown in the example. If your graph is large, consider batching or pre-filtering to services within a single bounded context to keep the analysis focused. The output schema is designed to be machine-readable—pipe the JSON directly into your architecture dashboard, CI/CD fitness function, or ADR generation workflow. For high-stakes decisions, always pair this automated analysis with human architectural review, especially when the output recommends restructuring services with high afferent coupling.

This prompt is designed to be called from a script or CI pipeline that extracts a dependency graph from service mesh data, API gateway configurations, or static analysis tools. The harness should treat the prompt as a pure reasoning step over structured input—no tool use, retrieval, or external API calls are required. The model receives a validated directed graph and returns a JSON risk assessment that downstream systems can consume for visualization, alerting, or architecture review workflows.

Before sending the graph to the model, validate the input structure: every edge target must exist in the node list, and the graph must be a valid directed graph with no dangling references. Reject malformed graphs before they reach the model. After receiving the model output, validate the JSON against the output contract—check that afferent_coupling, efferent_coupling, and instability fields are present for every service, that scores are numeric and within expected ranges, and that the ranked_services array is sorted by risk score descending. If validation fails, retry once with the validation errors appended to the prompt as [CONSTRAINTS]. Do not retry more than once without human intervention; repeated failures indicate a structural problem with the input graph or the prompt itself.

Log every invocation with the graph hash, model version, timestamp, and raw output for auditability. This is especially important when the prompt is used to inform architecture decisions that affect team structures or migration sequencing. For high-stakes architecture decisions—such as identifying services for extraction or merge—route the output to a human reviewer before acting on the ranked risk list. The reviewer should confirm that the coupling scores align with their operational knowledge of the system and that no counterintuitive rankings result from incomplete dependency data. The prompt does not replace architectural judgment; it accelerates the analysis that informs it.

Model choice matters here. The prompt requires reasoning over graph structure and numeric scoring, which most frontier models handle well. However, smaller or older models may produce malformed JSON or inconsistent scores. If you observe frequent validation failures, consider upgrading the model or adding a second validation pass with a different model as a cross-check. The prompt template includes [CONSTRAINTS] as a placeholder for injecting validation feedback on retry, and [RISK_LEVEL] to adjust the sensitivity of cyclic dependency detection and instability thresholds based on your team's tolerance for coupling risk.