Modularity Review

Structured review workflow inspired by Khononov's modularity analysis. Combines cargo-coupling's automated metrics with semantic code understanding.

Workflow

Step 1: Automated Analysis

cargo run -- coupling --ai $ARGUMENTS

Parse the output to understand current coupling state. AI output includes the full blind-spot manifest; treat "no issues" as "no observed issues", not as proof that no coupling risk exists.

Optional release/PR context:

# Time-series trend across git revisions
cargo run -- coupling --history $ARGUMENTS

# Diff current issues against the target branch
cargo run -- coupling --baseline main $ARGUMENTS

Step 2: Subdomain Classification

Read .coupling.toml for existing subdomain config. If absent, examine the codebase and suggest classification:

• Core: Modules providing competitive advantage (frequently evolving)
• Supporting: Stable business logic (CRUD, ETL, data pipelines)
• Generic: Solved problems (auth, logging, config, web framework)

The [subdomains] section informs essential-vs-accidental volatility. Core modules are expected to change; supporting/generic modules with high churn can indicate Accidental Volatility.

Step 3: Map Integrations

For each detected coupling, evaluate across 3 dimensions:

1. Strength: What knowledge is shared? Is it implicit or explicit?
2. Distance: Code structure + team boundaries + runtime coupling
3. Volatility: Business-driven (subdomain) + git-history-based

Look beyond explicit code dependencies for implicit coupling:

• Duplicated business logic across modules
• Shared magic constants/strings
• Assumptions about data format or ordering (connascence of meaning)
• Co-changing files without explicit dependencies

Automated issue signals to preserve in the review:

• Hidden Coupling: strong temporal co-change without an AST dependency
• Accidental Volatility: supporting/generic subdomain code with suspicious churn

Step 4: Apply Balance Rule

For each integration:

BALANCE = (STRENGTH XOR DISTANCE) OR NOT VOLATILITY

Flag issues by severity:

• Critical: High strength + high distance + high volatility
• Significant: Unbalanced in moderately volatile area
• Minor: Unbalanced in low-volatility area

Step 5: Generate Review

For each flagged issue, document:

1. What: Which modules and what knowledge is shared
2. Why problematic: Impact on changeability, cascading risk
3. Recommendation: Concrete improvement with Rust code example
4. Priority: Based on volatility and business impact

Output Format

# Modularity Review

**Date**: YYYY-MM-DD
**Scope**: [path]
**Health Grade**: [A-F]

## Subdomain Classification

| Module | Subdomain | Rationale |
|--------|-----------|-----------|

## Issues Found

### [Critical/Significant/Minor]: [Title]

**Modules**: source → target
**Strength**: [level] | **Distance**: [level] | **Volatility**: [level]

**Knowledge Leakage**: What internal knowledge is exposed
**Cascading Changes**: What breaks when this changes
**Recommendation**: Concrete fix with code example

## Good Design Decisions
[Patterns worth maintaining]

## Summary
[Key takeaways and prioritized action items]