Stable Dependencies Principle Compliance Review Prompt

This prompt is designed for architects and platform engineers who need to audit a codebase for violations of the Stable Dependencies Principle (SDP). The SDP states that a package should only depend on packages that are more stable than itself. When a stable package depends on an unstable package, that unstable package becomes difficult to change without breaking its dependents, creating a rigidity that slows delivery. The ideal user has already computed stability metrics (such as Martin instability) and has a dependency graph available, either from a static analysis tool or a build system. The prompt takes this graph and metrics as input and produces a ranked violation report with concrete refactoring direction, turning raw numbers into architectural judgment.

Use this prompt before a planned refactoring cycle, as part of an architecture review gate, or when a team reports that a supposedly stable module keeps breaking on upstream changes. It is most effective when you have a clear, machine-readable representation of your dependency graph and stability values. The prompt expects structured input, such as a JSON object mapping each package to its instability score and its direct dependencies. It will then reason about the direction of dependencies and flag cases where a more stable package depends on a less stable one. The output is a ranked list of violations, each with a severity assessment and a suggested refactoring direction, such as dependency inversion, extracting an interface, or moving the unstable package into a more stable layer.

Do not use this prompt for runtime coupling analysis, for greenfield design where no dependency graph exists yet, or as a substitute for static analysis tools that compute the raw metrics. This prompt adds architectural judgment on top of the metrics; it does not generate them. It is also not suitable for analyzing coupling in non-code systems, such as organizational dependencies or infrastructure topologies. For those, use a dedicated prompt from the System Boundary or Microservice Coupling playbooks. Before running this prompt, ensure your input data is accurate and complete. A missing dependency or an incorrectly calculated instability score will lead to false positives or missed violations. If your codebase uses stable abstractions (e.g., interfaces or abstract classes that are intentionally stable), include that context in the input to avoid flagging legitimate patterns as violations.

This prompt template is designed to be copied directly into your AI harness, IDE, or orchestration layer. It uses square-bracket placeholders for all variable inputs—your dependency graph, stability metrics, and output format requirements. The template enforces a structured violation report format so you can parse results programmatically, feed them into CI/CD gates, or route them to an architect for review. Before using it, ensure you have computed or extracted the necessary inputs: a list of packages/components, their incoming and outgoing dependencies, and any declared stability classifications (e.g., 'stable', 'unstable', 'abstract').

textCopy
You are an architecture compliance auditor. Your task is to review a dependency graph against the Stable Dependencies Principle (SDP), which states that a stable package (high fan-in, low fan-out) should not depend on an unstable package (low fan-in, high fan-out).

## INPUT
- Package dependency graph: [DEPENDENCY_GRAPH]
- Stability metrics per package (fan-in, fan-out, instability score I = fan-out / (fan-in + fan-out)): [STABILITY_METRICS]
- Declared stability classifications or allowed exceptions: [STABILITY_CLASSIFICATIONS]
- Known stable abstractions (interfaces, abstract classes) that may produce false positives: [STABLE_ABSTRACTIONS]

## CONSTRAINTS
- Flag only direct dependencies, not transitive ones, unless [INCLUDE_TRANSITIVE] is set to true.
- For each violation, check whether the unstable target is a stable abstraction (interface or abstract class). If so, classify it as a FALSE_POSITIVE and explain why.
- Ignore test-only dependencies unless [INCLUDE_TEST_DEPS] is true.
- Ignore dependencies on packages marked as [EXEMPT_PACKAGES].

## OUTPUT_SCHEMA
Return a JSON object with the following structure:
{
  "summary": {
    "total_packages_analyzed": <int>,
    "total_violations": <int>,
    "false_positives": <int>,
    "true_violations": <int>
  },
  "violations": [
    {
      "stable_package": "<package name>",
      "unstable_package": "<package name>",
      "stable_instability_score": <float>,
      "unstable_instability_score": <float>,
      "violation_severity": "HIGH" | "MEDIUM" | "LOW",
      "is_false_positive": <bool>,
      "false_positive_reason": "<explanation if applicable, else null>",
      "refactoring_direction": "<concrete suggestion: invert dependency, introduce abstraction, merge packages, or move code>"
    }
  ]
}

## RISK_LEVEL
[RISK_LEVEL]

## INSTRUCTIONS
1. For each stable package (I < [STABILITY_THRESHOLD]), examine its outgoing dependencies.
2. If a dependency target has I > [INSTABILITY_THRESHOLD], flag it as a potential violation.
3. Cross-reference flagged violations against [STABLE_ABSTRACTIONS] to identify false positives.
4. Assign severity: HIGH if the unstable package has I > 0.8 and the stable package has I < 0.2; MEDIUM if the gap is moderate; LOW if near the threshold.
5. For each true violation, provide a refactoring direction that reduces coupling in the stable-to-unstable direction.
6. If [RISK_LEVEL] is HIGH, include a warning that human review is required before any automated refactoring.

To adapt this template, replace each square-bracket placeholder with data from your build system, dependency analyzer, or architecture documentation. The [DEPENDENCY_GRAPH] can be a JSON adjacency list, a Mermaid diagram, or a structured text description—the model will parse any reasonable format. The [STABILITY_METRICS] should include at minimum fan-in, fan-out, and the computed instability score (I) for each package. If you don't have these pre-computed, pair this prompt with a dependency analysis tool like dependency-cruiser, jdeps, or a custom script that outputs the required metrics. The [STABLE_ABSTRACTIONS] list is critical for reducing false positives: include all interface packages, abstract base classes, and protocol definitions that are intentionally unstable but safe to depend on. For CI/CD integration, set [RISK_LEVEL] to "HIGH" to force a human-in-the-loop review gate; for informational dashboards, set it to "LOW" to suppress warnings. Test the prompt first against a known-clean module and a known-violating module to calibrate your [STABILITY_THRESHOLD] and [INSTABILITY_THRESHOLD] values before running it across the full codebase.

This prompt is designed to operate as a batch analysis step within a CI/CD pipeline or a scheduled architecture audit job. It expects a structured manifest of package metadata—stability metrics, dependency lists, and abstraction ratios—rather than raw source code. The application layer is responsible for extracting this data from the build system (e.g., JDepend, NDepend, or a custom dependency graph parser) and formatting it into the [PACKAGE_MANIFEST] input block. The model's role is pure reasoning over pre-computed metrics, not codebase exploration.

Validation and retry logic is critical because the output is a structured violation report intended for automated gating. Implement a JSON schema validator that checks for the presence of required fields (violating_package, depends_on, stability_metrics, refactoring_direction) and rejects malformed responses. On validation failure, retry once with a repair prompt that includes the schema and the raw output. If the second attempt fails, log the failure and fail the pipeline step open (warning) or closed (blocking) based on your risk tolerance. For high-assurance environments, route all violations to a human review queue before merging any refactoring PRs.

Model choice and grounding are straightforward here. Use a model with strong structured output capabilities (GPT-4o, Claude 3.5 Sonnet, or equivalent) and set temperature=0 for deterministic results. The prompt does not require retrieval-augmented generation (RAG) or tool use because all evidence is self-contained in the input manifest. However, you must ensure the upstream data extraction step is trustworthy—if the stability metrics fed into the prompt are wrong, the violation report will be wrong. Add a pre-flight check that verifies the instability values in the manifest sum correctly against the declared dependency counts before sending the payload to the model.