tsa-health-watch

name	tsa-health-watch
description	| Use when this capability is needed.

tsa-health-watch — Project + file health in one pass

Grades files A→F across 6 dimensions (complexity, structure, dependencies, duplication, size, git-hotspot). Daemon mode alerts on grade drops live.

When to use

Goal	Tool
Project portrait + worst files	health action=project
One-file deep dive	health action=file
Top hubs + sensory neurons	health action=overview
Find dead functions	health action=dead
Complexity hotspots (visualize)	health action=heatmap
Watch & alert on degradation	--watch-health CLI (Bash)

Procedure

One-shot triage (cold-start health audit)

Fan out in one message:

1. health action=project with max_files: 20 — grade distribution + worst-20
2. health action=dead with max_dead: 50 — pruning candidates
3. health action=overview — hub functions + entry points + 0-degree leaves

Read the verdict. If D/F files exist in worst-20, drill into each with health action=file to get the per-dimension breakdown + recommendation.

Single-file investigation

health action=file file_path="<path>"

Returns:

• grade: A | B | C | D | F (overall)
• dimensions: {complexity, structure, dependencies, duplication, size, git_hotspot}
• weakest_dimension: which one dragged grade down
• signal: healthy | moderate_depth | high_complexity | etc.
• recommendation: next concrete action

Long-running watch (daemon mode, T4)

Run in a separate terminal:

uv run tree-sitter-analyzer --watch-health \
  --threshold-grade C \
  --watch-interval 60 \
  --notify-channel stdout,file \
  --notify-file .tree-sitter-cache/health-events.jsonl \
  --on-degradation 'echo "ALERT: {file} {previous_grade}→{grade} ({recommendation})"'

Daemon fires alerts when:

• A file's grade gets strictly worse (B→C), OR
• A file crosses below --threshold-grade (B→D when threshold=C)

History persists in .ast-cache/health_scores.db table health_score_history.

Reading grades

Grade letters use A=best, F=worst ordering. Score ranges:

• A: 90-100 — healthy, no immediate action
• B: 80-89 — acceptable, minor smell
• C: 70-79 — review recommended
• D: 60-69 — refactor candidate
• F: <60 — high priority refactor

Weakest dimension tells you why:

• complexity → split functions
• structure → too many globals, missing types
• dependencies → too many imports / circular
• duplication → DRY opportunity
• size → split file
• git_hotspot → modified too often, churn risk

CLI equivalents

uv run tree-sitter-analyzer --project-health --output-format toon
uv run tree-sitter-analyzer <file> --file-health --output-format toon
uv run tree-sitter-analyzer --overview --output-format toon
uv run tree-sitter-analyzer --dead-code --output-format toon
uv run tree-sitter-analyzer --watch-health --threshold-grade C  # daemon

Anti-patterns

• Don't grade individual files when the question is "which 10 are worst" — use health action=project once instead of N file-health calls.
• Don't ignore dimensions and just look at the grade letter — the recommendation lives in the weakest dimension.
• Don't use --watch-health for one-shot checks — it's a long-running daemon.

Decision surface

project (when health action=project):
  grade_distribution: {A: n, B: n, C: n, D: n, F: n}
  worst_files: [{path, grade, score, weakest_dimension}, ...]

file (when health action=file):
  grade: A | B | C | D | F
  score: 0-100
  signal: healthy | moderate_depth | ...
  weakest_dimension: <name>
  dimensions: {complexity: 0-100, structure: 0-100, ...}
  recommendation: <next concrete action>

---

Source: aimasteracc/tree-sitter-analyzer — distributed by TomeVault.