Measure the actual coupling structure of a codebase using three signals: git co-change history, import/dependency edges, and semantic similarity. These signals are fused into a weighted graph, clustered into logical subsystems, and scored for boundary health, risk, and temporal stability.
Use this skill to ground architecture and refactoring decisions in empirical data rather than intuition. The output feeds directly into architecture, design, plan, and review as evidence.
Success looks like: numbered risk hotspots, measured boundary leakage, and prioritized suggestions with concrete scope.
-
Read results — use archobs show to extract metrics (no ad-hoc Python or Parquet libraries needed).
All show subcommands read from Parquet artifacts independently — run them in parallel when calling from an agent. This avoids sequential round-trips and is 5-6x faster.
Recommended for agents — run individual queries in parallel (avoids output truncation on large repos):
archobs show risks --top 10 --format json
archobs show clusters --sort leakage --format json
archobs show drift --format json
archobs show summary --format json
archobs show velocity --window 30 --compare --format json
archobs show suggestions --format json
archobs show team --format json
Note: show edges requires a cluster_id from show clusters or show velocity. Run it after those complete, targeting the top 2-3 leakiest or most active clusters:
archobs show edges <cluster_id> --format json
Or use --top-active to auto-select the most active clusters by file_change_count (eliminates the sequential round-trip):
archobs show edges --top-active 3 --format json
Large repos warning: --top-active output scales with cluster size. Hub clusters (100+ files) can have 15+ neighbors, producing output that exceeds context limits. Use --max-neighbors 10 to cap neighbor count per cluster:
archobs show edges --top-active 3 --max-neighbors 10 --format json
Edge JSON output schema (per neighbor):
neighbor_cluster, neighbor_label, total_weight, edge_count, leakage_share,
top_pairs: [{path_a, path_b, weight}]
leakage_share = total_weight / parent_cluster.external_weight — the fraction of the queried cluster's leakage flowing to this neighbor (e.g., 0.62 means 62% of the cluster's external coupling goes to this neighbor).
Convenience — compact all-in-one (agent-friendly, <50KB output):
archobs show all --compact --format json
The --compact flag limits output to 5 risks, 10 clusters, and edges for top-3 clusters only. Velocity always includes added_paths in JSON output.
When to use compact vs parallel queries:
- Repos < 500 files:
show all --compact is sufficient for a quick overview
- Repos 500–2000 files: parallel individual queries recommended — compact output truncates important context
- Repos > 2000 files: parallel queries required, and consider
--top limits to control output size
Full dump — for human review or when you need everything:
archobs show all --top 5 --format json
Avoid --top 0 on large repos — output can exceed context limits.
Additional queries:
archobs show files --format json
archobs show cluster-files <id> --format json
archobs show velocity --window 30 --compare --format json
archobs show risks --min-risk 0.5 --min-volatility 0.5 --format json
archobs show commits --since 30 --format json
archobs show hot-files --window 30 --top 10 --format json
archobs show suggestions --format json
Use --format table (default) for human-readable output, --format json for structured agent consumption, or --format csv for piping.
To discover column names for any artifact: archobs schema file_metrics
-
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).
-
Team analysis — check bus factor and knowledge concentration per cluster:
archobs show team --format json
archobs show team --sort concentration --format json
archobs show team --sort bus_factor --min-size 3 --format json
| Signal | Threshold | Meaning |
|---|
bus_factor | 1 | Single point of failure — one person owns the cluster |
hhi | > 0.5 | High knowledge concentration — few authors dominate |
top_author_pct | > 0.8 | Top contributor owns 80%+ of commits |
-
Fitness check — CI-gatable architecture health evaluation:
archobs check --format json
archobs check --ci
archobs check --max-file-risk 0.7 --max-leakage 0.5 --min-bus-factor 2 --ci
The check command is read-only — it never runs the pipeline or writes artifacts, making it safe for CI. Add to your CI pipeline:
- name: Architecture fitness check
run: archobs check --out .archobs --ci
Default thresholds: --max-file-risk 0.8 --max-leakage 0.6 --min-cohesion 0.4 --max-risk-mean 0.5 --min-bus-factor 2 --min-cluster-size 2
Bus factor check is optional — skipped if bus_factor.parquet doesn't exist (team analysis not run).
-
Route findings to the right skill:
- High leakage between clusters:
architecture (boundary redesign) or design (Facade — see structural pattern references)
- High-risk file with mixed concerns:
design (pattern selection and implementation guides)
- Multiple high-risk areas needing sequencing:
plan (prioritize refactoring order)
- Development momentum and feature prediction:
forecast internal engine (which clusters are active, what features are likely next). When running forecast in the same session, archobs artifacts are already available — the forecast skill can read directly from .archobs/ without re-extraction. added_paths are included by default in JSON output, surfacing exactly which new files are being built in each cluster.
Quick trajectory in the same session (no skill switch needed): run archobs show velocity --window 30 --compare --format json (added_paths included by default), check git branch -r --sort=-committerdate | head -20, and apply feature adjacency heuristics from the forecast skill. For full trajectory analysis with commit message themes and detailed interpretation, invoke the forecast skill (internal mode).
- Pre-merge health check:
finish (verify metrics did not regress)
- Thorough assessment of structural findings:
review (type: architecture)
-
Read suggestions (if generated):
If you already ran archobs show all --format json in step 4, suggestions are included under the "suggestions" key — no additional command needed.
When using individual parallel queries (step 4), add archobs show suggestions --format json to your parallel batch — this reads suggestions.json directly with no extra computation:
archobs show suggestions --format json
Alternatively, use archobs prompts --out .archobs for markdown-formatted output.
Each suggestion includes: priority, title, why (evidence), change (action), scope (affected files).
Steps that can be cut under pressure: team analysis (step 6), fitness check (step 7), suggestion loop, detailed edge inspection.
