coupling-review

Coupling Review

When this skill is activated, analyze the coupling structure of a specified module, feature, or the entire codebase and produce a docs/reviews/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 docs/reviews/COUPLING_REVIEW.md (create the docs/reviews/ folder if it does not exist) 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:

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