Circular Dependency Detection Prompt Template

This prompt is designed for platform engineers and architects who need to detect circular dependencies across a codebase before they cause build failures, deployment deadlocks, or refactoring paralysis. Use it when you have access to a dependency graph, import manifest, or static analysis output and need a ranked, severity-classified list of cycles. The prompt assumes the input is a structured representation of file-level or module-level dependencies. It is not a replacement for static analysis tools; it is a reasoning layer that classifies, ranks, and explains cycles so teams can prioritize remediation. This prompt belongs in architecture review workflows, CI/CD quality gates, and refactoring planning sessions where human judgment is needed to interpret tool output.

The ideal input is a machine-generated dependency graph—such as the output of madge, dependency-cruiser, or a language-specific import analyzer—formatted as a list of edges or an adjacency map. The prompt works best when the input includes file paths, module names, and dependency direction. It can handle graphs with hundreds of nodes, but for very large codebases, you should partition the input by subsystem or bounded context to avoid token limits and reasoning degradation. Do not use this prompt on raw source code without first running static analysis; the model is not a parser and will hallucinate dependencies when asked to read arbitrary files. Also avoid using it for runtime or dynamic dependency detection, where reflection, service discovery, or lazy loading creates edges invisible to static analysis.

The prompt classifies each cycle by severity—blocking, high, medium, or low—based on cycle length, the number of downstream dependents, and whether the cycle crosses architectural boundaries. It produces a ranked list with file paths, cycle length, and a brief explanation of why the cycle is problematic. Use this output to prioritize remediation: short cycles in core modules are usually the most urgent. Before acting on the results, validate the top findings against your build system and runtime behavior. False positives can arise from test-only imports, type-only references, or dynamic imports that static tools misrepresent. When integrating this prompt into a CI/CD pipeline, pair it with a threshold rule that fails the build only when new blocking cycles are introduced, not when pre-existing debt is detected.

The prompt below is designed to accept a structured dependency graph and return a ranked, classified report of all circular dependency chains. It is built for platform engineers and architects who need to programmatically identify and prioritize cycles before they cause build failures, deployment deadlocks, or refactoring paralysis. The template uses square-bracket placeholders so you can wire it directly into an application harness without manual editing.

textCopy
You are a static analysis engine specialized in dependency graph evaluation. Your task is to analyze the provided dependency graph and detect, rank, and classify all circular dependency chains.

## INPUT
[DEPENDENCY_GRAPH]

## CONSTRAINTS
- Exclude cycles that exist only in test files or test directories unless [INCLUDE_TEST_CYCLES] is set to true.
- Exclude cycles that involve only dynamic imports (e.g., `import()`, `require()` inside functions) unless [INCLUDE_DYNAMIC_IMPORTS] is set to true.
- A cycle must contain at least [MIN_CYCLE_LENGTH] nodes to be included in the report.
- Ignore self-referencing files (a file importing itself) unless [INCLUDE_SELF_REFERENCES] is set to true.
- If [EXCLUDE_PATTERNS] is provided, ignore any node whose path matches one of the glob patterns.

## OUTPUT_SCHEMA
Return a valid JSON object with this exact structure:
{
  "summary": {
    "total_cycles_found": <integer>,
    "max_cycle_length": <integer>,
    "cycles_by_severity": {
      "critical": <integer>,
      "high": <integer>,
      "medium": <integer>,
      "low": <integer>
    }
  },
  "cycles": [
    {
      "cycle_id": "<string, e.g., 'CYCLE-001'>",
      "cycle_length": <integer>,
      "severity": "<critical|high|medium|low>",
      "severity_rationale": "<string explaining why this severity was assigned>",
      "nodes": [
        {
          "file_path": "<string>",
          "import_statement": "<string, the specific import that creates the cycle>",
          "import_type": "<static|dynamic|re-export>"
        }
      ],
      "remediation": {
        "suggested_action": "<extract_interface|invert_dependency|merge_modules|break_with_events|re-evaluate_boundary>",
        "description": "<string with concrete refactoring guidance>",
        "estimated_effort": "<low|medium|high|extreme>",
        "breaking_change_risk": "<low|medium|high>"
      }
    }
  ],
  "false_positives_excluded": [
    {
      "cycle_description": "<string>",
      "exclusion_reason": "<dynamic_import|test_only|below_min_length|excluded_pattern|self_reference>",
      "nodes_involved": ["<string>"]
    }
  ]
}

## SEVERITY CLASSIFICATION RULES
- **critical**: Cycle length >= 5 OR cycle spans >= 3 top-level directories OR cycle includes a module that is a public API surface.
- **high**: Cycle length 3-4 OR cycle spans 2 top-level directories OR cycle includes a module with >= 10 dependents.
- **medium**: Cycle length 2-3 within a single top-level directory, not involving public API surfaces.
- **low**: Cycle length 2 within the same subdirectory, involving only internal utility modules.

## REMEDIATION GUIDANCE
For each cycle, recommend the most appropriate structural fix:
- **extract_interface**: Create a shared interface or abstract class that both modules depend on, breaking the direct cycle.
- **invert_dependency**: Reverse the direction of one dependency so the more stable module depends on the less stable one.
- **merge_modules**: If the cycle indicates false modularity, merge the modules into a single cohesive unit.
- **break_with_events**: Replace a direct call with an event or message to decouple the modules at runtime.
- **re-evaluate_boundary**: The cycle may indicate that the module boundary itself is wrong and needs redesign.

## INSTRUCTIONS
1. Parse the dependency graph to identify all strongly connected components.
2. For each SCC with >= [MIN_CYCLE_LENGTH] nodes, extract the exact cycle paths.
3. Apply the exclusion filters from [CONSTRAINTS].
4. Classify each remaining cycle by severity.
5. Generate remediation suggestions for each cycle.
6. List all excluded cycles in `false_positives_excluded` with clear reasons.
7. Return ONLY the JSON object. No markdown fences, no commentary.

Adaptation notes: Replace [DEPENDENCY_GRAPH] with a structured representation of your dependency graph—this can be a JSON adjacency list, a list of {from, to, import_type} edges, or a serialized graph object from your build tool. The [EXCLUDE_PATTERNS] placeholder accepts glob patterns like "**/*.test.*" or "**/__mocks__/**". Set [INCLUDE_TEST_CYCLES], [INCLUDE_DYNAMIC_IMPORTS], and [INCLUDE_SELF_REFERENCES] to boolean strings ("true" or "false") based on your analysis scope. [MIN_CYCLE_LENGTH] should be an integer, typically 2 or 3 depending on whether you consider direct mutual imports as cycles worth reporting.

Before wiring this into a CI/CD pipeline, validate the output against the schema. Common failure modes include the model returning cycles shorter than [MIN_CYCLE_LENGTH], misclassifying severity when the graph lacks directory hierarchy metadata, or failing to populate the false_positives_excluded array. Run this prompt against a known dependency graph with documented cycles first, then compare the model's output to your ground truth. If the prompt is used in a regulated or safety-critical codebase, add a human review step before any automated refactoring is triggered from the remediation suggestions.

The circular dependency detection prompt is designed to be integrated into a deterministic pipeline, not used as a one-off chat. The prompt expects a structured representation of your dependency graph—typically a list of file paths and their direct imports—and returns a ranked list of cycles. The application layer is responsible for extracting this graph from the codebase (using tools like madge, dependency-cruiser, or language-specific AST parsers), formatting it as the [DEPENDENCY_GRAPH] input, and then validating the model's output before it reaches a developer or a build gate.

The implementation harness should enforce a strict contract. Before calling the model, validate that the [DEPENDENCY_GRAPH] input is a complete, non-empty list of {file, imports[]} objects. After receiving the model's response, parse the JSON output and run a structural validator that checks: (1) every reported cycle is a real cycle by walking the original graph, (2) no cycle is reported twice under a different rotation, and (3) the severity field is one of the allowed enum values. If validation fails, retry once with the validation errors appended to the [CONSTRAINTS] field. If the retry also fails, log the raw output and alert a human; never silently accept a malformed cycle report. For high-risk repositories (e.g., monoliths with strict layering rules), route critical severity cycles to a review queue that blocks merges until an architect acknowledges the finding.

Model choice matters here. The task requires precise, exhaustive graph traversal, which is a known weakness for smaller models. Use a model with strong reasoning capabilities (e.g., GPT-4, Claude 3.5 Sonnet, or Gemini 1.5 Pro) and set the temperature to 0 to minimize variance. If you are scanning a very large codebase with thousands of files, you must pre-process the graph to reduce noise: filter out test files (unless [INCLUDE_TEST_PATHS] is true), exclude known dynamic imports that your static analyzer cannot resolve, and consider partitioning the graph by top-level directory before sending it to the model. The prompt's [EXAMPLES] field should be populated with 1-2 real, anonymized cycles from your codebase to calibrate the model's output format. Finally, log every invocation with the prompt version, model, graph hash, and validation result. This creates an audit trail for when a cycle is missed or a false positive is raised, allowing you to debug the prompt rather than the architecture.