---
name: coupling-review
description: Analyzes a module or codebase for coupling quality. Distinguishes intentional from accidental coupling, identifies problematic dependencies, and recommends concrete improvements.
metadata:
  author: janmarkuslanger
  version: "1.0"
---

# Coupling Review

When this skill is activated, analyze the coupling structure of a specified module, feature, or the entire codebase and produce a `COUPLING_REVIEW.md` report.

## Clarifying Questions

Before starting the review, ask the engineer the following questions. Skip any already clearly answered in the conversation. **Wait for the answers before proceeding.**

1. What is the scope — a specific module or feature, or the full codebase?
2. What is the goal of this review? (e.g. before a refactor, identifying change-propagation risk, understanding dependencies)
3. Which areas of the codebase change most frequently — where does coupling hurt the most today?
4. Are there specific cross-module or cross-context dependencies you already suspect are problematic?

## Steps

1. Use the answers above to set scope and focus; fall back to full codebase only if scope was not specified
2. Read the relevant source files and map all dependencies between components
3. Classify each coupling by type and assess whether it is intentional or accidental
4. Identify coupling smells: hidden dependencies, inappropriate intimacy, unstable dependencies, circular references
5. Propose concrete refactoring steps for each problematic coupling

## Output

Write a file called `COUPLING_REVIEW.md` in the project root with the following sections:

### 1. Scope
What was analyzed (files, modules, feature boundaries).

### 2. Dependency Map
A Mermaid diagram of all identified dependencies within the analyzed scope:

```mermaid
graph TD
    A[ModuleA] -->|imports| B[ModuleB]
    A -->|calls| C[Service]
    B -->|reads| D[(Database)]
```

Use different arrow labels to indicate coupling type: `imports`, `calls`, `extends`, `reads`, `writes`, `emits`, `listens`.

### 3. Coupling Inventory
A table of all significant couplings found:

| From | To | Type | Intentional? | Strength | Assessment |
|------|----|------|-------------|----------|------------|
| OrderService | PaymentGateway | direct call | yes | high | OK — stable external contract |
| OrderService | UserRepository | direct import | no | high | Problem — crosses bounded contexts |

**Strength**: `low` (can change independently) | `medium` | `high` (change in one forces change in other)

**Assessment**: `OK` | `Tolerable` | `Problem` | `Critical`

### 4. Identified Issues
For each `Problem` or `Critical` coupling, a dedicated entry:

**Issue: {Short Name}**
- **What**: describe the coupling
- **Why it's a problem**: testability impact, change propagation, wrong layer violation, etc.
- **Evidence**: file path and line numbers
- **Recommended fix**: concrete refactoring — interface extraction, dependency injection, event decoupling, etc.

### 5. Circular Dependencies
List any circular dependencies found. These are always problems. Include the full cycle and a recommended break point.

### 6. Summary
| Category | Count |
|----------|-------|
| Total couplings analyzed | N |
| Intentional & healthy | N |
| Tolerable (document but accept) | N |
| Problems (should fix) | N |
| Critical (fix before next release) | N |

One paragraph of overall assessment: is the coupling structure sound, or does it indicate deeper design problems?

## Rules

- Distinguish between coupling that is inherent to the domain (acceptable) and coupling that is a design accident (should be fixed)
- Do not flag all coupling as bad — coupling is necessary; the question is whether it is managed consciously
- Always provide file paths and line numbers for identified issues — vague findings are not actionable
- Prioritize findings by impact on testability and change cost, not by theoretical purity
- If the scope is large, focus depth on the highest-risk areas rather than producing a shallow full-codebase scan