Cross-Metric Insights

Cross-Metric Insights

The Cross-Metric Insights plugin synthesizes data from all base metrics to produce validated architectural insights with prioritized refactoring recommendations. Unlike individual metrics that provide isolated views, this plugin validates findings across multiple dimensions (structure + evolution) to reduce false positives and prioritize actionable improvements.

Overview

Cross-Metric Insights combines:

• Static analysis (Ricci Curvature, Centrality, Modularity, Hierarchy, Package Metrics, SCC)
• Evolution data (MSR churn, co-change patterns)
• Synthesis algorithms to produce validated, prioritized insights

The plugin operates in Phase 2 of metric computation, after all base metrics have been computed, allowing it to access their results through the ComputedMetricsCache.

Why It Matters

Validation Reduces False Positives

A single metric might flag an issue, but cross-validation confirms it:

Single Metric Finding	Cross-Metric Validation	Action
Ricci: Negative curvature edge	+ MSR: High churn on that edge	Confirmed bridge - fix urgently
MSR: High churn file	+ Ricci: Hub pattern detected	Critical hotspot - split by domain
SCC: Cycle detected	+ MSR: High churn in cycle	Hot cycle - break immediately
MSR: Wrong boundary	+ Ricci: Would create negative curvature	Merge domains instead of linking

Prioritization Based on Real Impact

The plugin ranks all issues by combining:

• Static severity (from Ricci, Centrality, etc.)
• Evolution cost (churn, co-change frequency)
• Impact score (how many modules affected)

This produces a prioritized refactoring queue where the highest-impact fixes are clearly identified.

Metrics

Temporal Validation Metrics

These metrics validate structural findings with evolution data:

• insights.validated_bridge_count: Number of Ricci negative edges confirmed by high churn/co-change
• insights.validated_bridge_severe_count: Severe validated bridges (curvature < -2.0, churn > 1000)
• insights.validated_hub_count: MSR hotspots that are also Ricci hub patterns
• insights.hot_cycle_count: SCC cycles with total churn > 1000
• insights.stable_bridge_count: Bridges with low churn (acceptable, monitor only)

Interpretation:

• High validated_bridge_severe_count indicates confirmed architectural problems requiring immediate attention
• stable_bridge_count > 0 means some structural bridges are acceptable (low change frequency)

Domain Alignment Metrics

These metrics check if logical structure matches change patterns:

• insights.domain_misalignment_count: Wrong boundaries that should merge (predicted negative curvature)
• insights.cross_community_cochange: Files in different modularity communities that co-change
• insights.community_health_min: Minimum health score across all communities
• insights.community_health_avg: Average health score across communities

Interpretation:

• High domain_misalignment_count suggests architectural boundaries don’t match real change patterns
• Low community_health_avg indicates poor domain separation

Layer Discipline Metrics

These metrics measure the cost of hierarchy violations:

• insights.hot_layer_violation_count: Hierarchy violations with churn > 500
• insights.layer_violation_debt_score: Total churn associated with layer violations
• insights.stable_violation_count: Violations with low churn (can wait)

Interpretation:

• High layer_violation_debt_score means layer violations are actively being worked on (high cost)
• Focus on hot_layer_violation_count first - these are the expensive violations

Dependency Health Metrics

These metrics identify fragile dependencies:

• insights.fragile_core_count: Core-periphery core nodes with high instability
• insights.stable_periphery_count: Periphery nodes that should be in core
• insights.unstable_dep_debt_score: Cost of unstable dependency anti-patterns
• insights.dependency_health_score: Overall dependency health (0-100)

Interpretation:

• fragile_core_count > 0 indicates core modules that are too unstable (architectural risk)
• High unstable_dep_debt_score means stability violations are causing real maintenance cost

Refactoring Prioritization Metrics

These metrics help prioritize refactoring work:

• insights.top_priority_score: Highest priority refactoring score
• insights.surgery_queue_size: Number of prioritized surgery suggestions
• insights.total_technical_debt_score: Aggregate debt measurement
• insights.estimated_refactoring_effort: Estimated effort for top 5 surgeries

Interpretation:

• top_priority_score > 500 indicates critical refactoring needed immediately
• surgery_queue_size shows how many actionable improvements are available
• total_technical_debt_score provides a single number to track over time

Aggregate Metrics

• insights.total_validated_issues: Total validated structural problems
• insights.total_domain_issues: Total domain alignment problems
• insights.total_layer_issues: Total layer discipline problems
• insights.total_dependency_issues: Total dependency health problems
• insights.overall_health_score: Overall architecture health (0-100)

Configuration

The plugin automatically runs in Phase 2 if enabled. No special configuration needed:

metrics:
  - id: cross_metric_insights
    enabled: true

However, you should enable the base metrics it depends on:

metrics:
  # Phase 1: Base metrics
  - id: scc
    enabled: true
  - id: centrality
    enabled: true
  - id: modularity
    enabled: true
  - id: hierarchy
    enabled: true
  - id: package_metrics
    enabled: true
  - id: msr
    enabled: true
  - id: ricci_curvature
    enabled: true
    config:
      pattern_detection: true
      surgery_suggestions: true

  # Phase 2: Synthesizer (automatically uses Phase 1 results)
  - id: cross_metric_insights
    enabled: true

Policy Examples

Prevent Validated Critical Issues

policy:
  invariants:
    - metric: insights.validated_bridge_severe_count
      op: "=="
      value: 0
    - metric: insights.validated_hub_count
      op: "<="
      value: 2
    - metric: insights.hot_cycle_count
      op: "=="
      value: 0

Monitor Technical Debt

policy:
  invariants:
    - metric: insights.total_technical_debt_score
      op: "<="
      value: 5000
    - metric: insights.overall_health_score
      op: ">="
      value: 70

Track Domain Health

policy:
  invariants:
    - metric: insights.domain_misalignment_count
      op: "<="
      value: 5
    - metric: insights.community_health_avg
      op: ">="
      value: 0.6

Use Cases

1. Validated Problem Identification

Instead of acting on every Ricci negative edge, focus on validated bridges:

metrics:
  - id: ricci_curvature
  - id: msr
  - id: cross_metric_insights

policy:
  invariants:
    - metric: insights.validated_bridge_severe_count
      op: "=="
      value: 0

2. Refactoring Prioritization

Use the surgery queue to plan refactoring sprints:

# The plugin automatically produces a prioritized queue
# Check insights.top_priority_score and insights.surgery_queue_size
# Focus on top 5 surgeries for maximum impact

3. Domain Boundary Validation

Validate that architectural boundaries match change patterns:

policy:
  invariants:
    - metric: insights.domain_misalignment_count
      op: "<="
      value: 3
    - metric: insights.cross_community_cochange
      op: "<="
      value: 10

Details Output

The plugin provides comprehensive details in the UI schema:

Validated Bridges

{
  "from": "shared/utils",
  "to": "features/auth/api",
  "frc_curvature": -2.3,
  "churn": 2500,
  "cochange_count": 12,
  "severity": "severe",
  "surgery_recommendation": "Extract interface or apply dependency inversion"
}

Critical Hotspots

{
  "node_id": "shared/helpers",
  "msr_churn": 3200,
  "msr_centrality": 45,
  "incident_negative_curvature": 1.2,
  "is_ricci_hub": true,
  "combined_score": 144000,
  "priority_rank": 1
}

Prioritized Surgeries

{
  "surgery_type": "SplitHub",
  "location": ["shared/helpers"],
  "ricci_severity": 0.8,
  "churn_score": 3200,
  "cochange_score": 45,
  "priority_score": 892.5,
  "estimated_impact": "High impact - refactor immediately"
}

Relationship to Other Metrics

This plugin depends on and synthesizes data from:

• Ricci Curvature: Provides structural bridges, hubs, and surgery suggestions
• MSR: Provides churn, co-change, and hotspot data
• Centrality: Provides hub identification and bottleneck detection
• Modularity: Provides community assignments for domain analysis
• Hierarchy: Provides layer violation data
• Package Metrics: Provides stability data for dependency health
• SCC: Provides cycle detection for hot cycle analysis
• Core-Periphery: Provides core/periphery classification

Best Practices

1. Enable All Base Metrics: The plugin works best when all base metrics are enabled
2. Focus on Validated Issues: Prioritize validated_bridge_severe_count over raw Ricci findings
3. Use Surgery Queue: Follow the prioritized surgery queue for maximum impact
4. Track Health Score: Monitor overall_health_score over time to measure improvement
5. Combine with Policies: Use policy invariants to prevent regression

Limitations

1. Requires Base Metrics: The plugin needs base metrics to be computed first
2. Git History Required: Some insights require MSR data (git history)
3. Simplified Algorithms: Some algorithms are simplified - full implementation would parse UI schemas more thoroughly
4. Performance: Cross-metric analysis adds computation time, but provides high-value insights

References

• MacCormack, A., et al. (2006). “A Framework for the Design of Modular Software Systems”
• Zimmermann, T., et al. (2005). “Mining version histories to guide software changes”
• Ollivier, Y. (2009). “Ricci curvature of Markov chains on metric spaces”
• Newman, M. E. J., & Girvan, M. (2004). “Finding and evaluating community structure in networks”