Structural Coupling And Volatility Analyzer

Structural Coupling and Volatility Analyzer

Measure macro-level dependency health across modules and bounded contexts.

When to Use

• Periodic architectural health checks
• Major refactoring initiatives
• CI gates for dependency drift
• Package or module boundary audits

Scope

• Scans: package and module dependency graphs, import statements, package declarations, and version-control churn needed to compute Ca, Ce, instability, abstractness, and distance from the main sequence.
• Exclusions: generated/vendor code and local refactors that do not change the external dependency graph materially.
• Fallback: if module boundaries are weak or inconsistent, use the shared conventions heuristic order and downgrade to warning with low confidence.
• Routing: defer method-level connascence and complexity to Complexity and Code Health Analyzer and extraction planning to Component Extraction and Tactical Forking Analyzer.

Workflow

1. Calculate coupling.
   • Compute afferent coupling (Ca) and efferent coupling (Ce).
   • Flag modules with extreme inbound or outbound dependency counts.
2. Evaluate resilience.
   • Compute instability and abstractness for major modules.
   • Identify stable-but-concrete or abstract-but-unstable modules.
3. Measure distance from the main sequence.
   • Calculate distance and flag zone-of-pain or zone-of-uselessness violations.
4. Report findings.
   • Return the top problematic modules.
   • Include Ca, Ce, I, A, D, plus a separate volatility signal from git history.

Rules

• Use static analysis, AST parsing, and import-graph evaluation only.
• Keep the analysis deterministic and language-agnostic.
• Prefer module-level architecture boundaries over file-level noise.
• Do not infer volatility from file size alone.
• Treat central shared modules as structural anchors rather than failures unless they are both concrete and unstable.

Shared Conventions

• Follow the repository-wide conventions in shared-skill-conventions.
• Use the canonical output contract, severity levels, confidence rubric, routing rules, and false-positive downgrades defined there.
• If this skill is not the closest match, defer to the routing guidance in the shared conventions file.

Output

Return:

• Top zone-of-pain and zone-of-uselessness modules
• Coupling and instability metrics
• Architectural health summary
• CI-ready pass or fail output