Acyclic Dependencies Principle Validation Prompt

This prompt is for platform engineers and architects who need to enforce the Acyclic Dependencies Principle (ADP) across a codebase. It takes a pre-computed dependency graph as input and produces a structured violation report identifying every cycle between packages or components, ranked by severity. The primary job-to-be-done is integrating architectural validation into a build pipeline, CI/CD gate, or pre-merge review so that cycles are caught before they compound into untestable, unbuildable tangles. The ideal user already has a dependency extraction tool in their toolchain and needs a deterministic, repeatable analysis step that produces machine-readable results.

The prompt is designed to be deterministic: it does not guess about dependencies, infer missing edges, or explore the codebase live. It requires a complete dependency graph in a defined format as the [INPUT] and focuses entirely on cycle detection, severity classification, and refactoring guidance. The output schema includes cycle length, participating nodes, entry points for breaking the cycle, and a severity score based on cycle size and the stability of the involved components. This makes the output suitable for automated gating—if the severity exceeds a configured threshold, the build can fail with a detailed report.

Do not use this prompt for live codebase exploration, for generating the dependency graph itself, or for analyzing runtime call graphs that include dynamic dispatch, reflection, or service meshes. It assumes the graph already exists and needs validation. For codebases with intentional cycles (such as test utilities that import from production code), provide those exemptions as part of the [CONSTRAINTS] input so the prompt can exclude them from violation reporting. The next step after reading this section is to prepare your dependency graph in the expected input format and configure the severity thresholds that match your team's architectural standards.

This prompt template is the core engine for an automated ADP gate. It is designed to be dropped into a CI/CD pipeline or a local pre-commit hook. The prompt instructs the model to act as a strict architecture validator, analyzing a provided dependency graph or package structure to find cycles. It does not just list cycles; it requires the model to propose concrete, actionable refactoring options for each one, making the output directly useful for an engineering team.

textCopy
You are an expert software architect enforcing the Acyclic Dependencies Principle (ADP). Your task is to analyze the provided dependency graph for a codebase and produce a strict violation report.

# INPUT
[DEPENDENCY_GRAPH]

# CONSTRAINTS
- A dependency graph is a directed graph where nodes are components/packages and edges represent 'depends on' relationships.
- A cycle is any path where you can start at a node and follow directed edges to return to the same node.
- Ignore self-referencing edges (a node depending on itself).
- If a cycle exists only within a test scope, flag it with a lower severity.
- Do not invent dependencies. Only use the provided [DEPENDENCY_GRAPH].

# OUTPUT_SCHEMA
You must respond with a valid JSON object conforming to this structure:
{
  "summary": {
    "total_components": <integer>,
    "total_dependencies": <integer>,
    "cyclic_groups_found": <integer>,
    "is_acyclic": <boolean>
  },
  "cycles": [
    {
      "cycle_id": "<string>",
      "severity": "<CRITICAL|WARNING>",
      "components_in_cycle": ["<string>"],
      "cycle_length": <integer>,
      "violating_edges": [
        {"from": "<string>", "to": "<string>"}
      ],
      "refactoring_options": [
        {
          "strategy": "<Dependency Inversion|Extract Interface|Move Component|Break Edge>",
          "description": "<string>",
          "target_edge": {"from": "<string>", "to": "<string>"}
        }
      ]
    }
  ]
}

# INSTRUCTIONS
1. Parse the [DEPENDENCY_GRAPH] to identify all strongly connected components.
2. For each cycle found, generate a unique `cycle_id`.
3. Assign a `CRITICAL` severity to cycles in production code and `WARNING` to cycles that exist only in test code.
4. For each cycle, propose at least one concrete refactoring option by specifying a target edge to break and a standard architectural strategy.
5. If no cycles are found, return an empty `cycles` array and set `is_acyclic` to true.

To adapt this template, replace the [DEPENDENCY_GRAPH] placeholder with a machine-readable representation of your package structure. This could be a JSON object mapping package names to lists of their dependencies, a list of edge objects, or even a raw adjacency list. The critical adaptation is ensuring the input format is consistent and unambiguous for the model. For high-risk production gates, always follow this prompt with a validation step that programmatically verifies the reported cycles exist in the original graph to catch model hallucinations before blocking a build.

This prompt is designed to be integrated into a CI/CD pipeline as a non-blocking or blocking quality gate, depending on your team's tolerance for dependency debt. The harness should invoke the LLM after a dependency graph has been extracted from the codebase using a deterministic tool like madge, dependency-cruiser, or a language-specific analyzer. The LLM's role is not to discover cycles—the static analysis tool does that with perfect accuracy—but to interpret the results, classify severity, and propose refactoring options that a tool cannot. The harness must therefore supply the prompt with a pre-computed list of cycles, not raw source code.

The implementation flow should follow a strict sequence: (1) run the static analysis tool to generate a JSON dependency graph and a list of cycles; (2) filter out known false positives using a configurable allowlist of test-only cycles, dynamic imports, or intentional exceptions; (3) construct the prompt payload by injecting the filtered cycle list into the [CYCLE_LIST] placeholder, along with the [PACKAGE_RULES] describing your architectural boundaries; (4) call the model with a low temperature setting (0.0–0.2) to maximize deterministic output; (5) validate the response against the expected [OUTPUT_SCHEMA] before accepting it; and (6) publish the validated report as a build artifact or PR comment. If validation fails, retry once with the error message appended to the prompt context, then fail the check and alert the platform team.

The output schema must be strictly validated before the report is surfaced to developers. Each cycle entry must contain a cycle_id, a severity from the allowed enum (BLOCKER, HIGH, MEDIUM, LOW), a cycle_path array of package names, and at least one refactoring_option with a strategy field. If the model returns a cycle not present in the input [CYCLE_LIST], reject the entire response as a hallucination. If a severity value is outside the allowed enum, map it to MEDIUM and flag the anomaly in logs. The harness should also check that refactoring_option suggestions reference actual packages from the input and do not invent package names. For high-risk repositories where a false positive could block a release, route BLOCKER and HIGH severity findings to a human reviewer via a PR comment or ticketing system before the build gate enforces the block.

Model choice matters for this workflow. Use a model with strong reasoning capabilities and structured output support, such as Claude 3.5 Sonnet or GPT-4o, configured with JSON mode or structured outputs enabled. Avoid smaller or older models that may struggle with the multi-step reasoning required to propose viable refactoring strategies. Log every invocation with the prompt version, model identifier, cycle count, validation pass/fail status, and any schema violations. This trace data is essential for debugging false positives, tuning severity thresholds, and defending architectural decisions during team discussions. Start with a non-blocking advisory mode for two sprints to calibrate severity thresholds against your team's actual tolerance before promoting the check to a blocking gate.