Interpret key metrics (see references/interpreting-metrics.md):
File-level risk (archobs show risks):
| Signal | Threshold | Meaning |
|---|
risk | > 0.5 | High combined risk — prioritize for refactoring |
xnbr | > 0.35 | Cross-boundary neighbor ratio — file bridges multiple concerns |
hubness | > 0.45 | High fan-in — changes here have wide blast radius |
volatility | relative | High churn rate compared to peers |
Filter directly: archobs show risks --min-risk 0.5 --format json or --min-xnbr 0.35 or --min-hubness 0.45 or --min-volatility 0.5.
Cluster-level health (archobs show clusters):
| Signal | Threshold | Meaning |
|---|
leakage | > 0.20 | Boundary is porous — responsibilities bleed across |
cohesion | < 0.30 | Weak internal connectivity — cluster may be artificial |
conductance | relative | Cross-boundary edge fraction (lower is healthier) |
Drift (archobs show drift):
| Signal | Threshold | Meaning |
|---|
ari_prev | < 0.50 | Architecture is unstable — subsystem map is reshuffling |
modularity | declining | Boundaries are weakening over time |
Drift trend interpretation — the trend across windows matters more than any single value:
| Pattern | Interpretation |
|---|
| ARI rising toward 1.0 | Stabilizing — architecture is settling after upheaval |
| ARI falling across windows | Degrading — boundaries are being broken |
| ARI oscillating | Volatile — team is experimenting with structure |
| Modularity declining while ARI rises | New cross-cutting features are landing in a stable structure |
When reporting drift, always examine the ARI trend (last 2+ windows) rather than applying a single threshold. A codebase with ARI 1.0 → 0.38 → 0.58 → 0.77 is stabilizing, not unstable.
Young repos: Repos with less than 6 months of history may produce fewer drift windows than configured. This is expected — interpret the trend with whatever windows are available.
Velocity (archobs show velocity):
| Signal | Suggests |
|---|
High growth_ratio | New capability being built — define boundaries early |
High churn_ratio | Feature refinement/iteration in progress |
High acceleration (with --compare) | Active development push |
Low acceleration | Work winding down — safe window for refactoring |
High recent_file_changes_30d in cluster | Focused sprint in one area |
High external_inbound_weight | Gravitational center — other clusters pull toward this one |
--compare flag: Use --compare to enable acceleration metrics (compares current window to prior window of the same length). Without it, only absolute velocity is shown. With it, you get prior_commit_count, acceleration (current/prior ratio), and is_emerging (true when a cluster had zero commits in the prior window).
Velocity sort order: show velocity sorts by distinct_commits by default. Use --sort file_change_count or --sort acceleration (requires --compare) for alternative orderings. Note that show edges --top-active sorts by file_change_count, which can produce a different ranking than the default velocity output.
Known limitation — deleted files: Velocity uses an inner join between commits and the current file inventory. Files deleted during the analysis window have no cluster assignment, so their commits are silently dropped. The deleted_count column reflects only deletions of files that still exist in the inventory (renamed/moved), not files fully removed from the codebase.
Filter to active clusters: archobs show velocity --window 30 --compare --min-acceleration 1.0 --min-growth-ratio 0.1 --format json
For detailed velocity signal interpretation (feature adjacency reasoning, acceleration context, convergent hub patterns), see the forecast skill (internal engine).
