| name | systems-health |
| description | Measure the health of a software development system using stocks, flows, and feedback loops. Use when someone says "systems health", "how's the project going", "health check", "measure our process", "are we shipping fast enough", "what's slowing us down", or for periodic check-ins on development velocity and quality. Pulls data from git, GitHub, and CI to diagnose what's working and what's broken. Outputs to .tap/system-health.md. |
Systems Health
Diagnose the development system. Measure stocks, flows, and feedback loops. Find what's sick and prescribe the cheapest fix.
Process
- Collect data
- Measure stocks
- Measure flows
- Assess feedback loops
- Measure complexity signals
- Diagnose and prescribe
- Write .tap/system-health.md
1. Collect Data
Pull from available sources (skip any that aren't accessible):
git log --oneline --since="30 days ago" → commit frequency
git log --oneline --since="90 days ago" → longer trend
git shortlog -sn --no-merges --since="30 days ago" → contributor activity
gh pr list --state all --limit 50 → PR lifecycle
gh pr list --state open → current open PRs
gh run list --limit 20 → CI pass/fail rate
gh issue list --state all --label bug --limit 50 → bug lifecycle
gh issue list --state open → current open issues
Also read if available:
.tap/tap-audit.md → prior assessment context.tap/system-health.md → prior health snapshot for trend comparison- Test runner output → test count, coverage
Time windows: Default to 30-day snapshot with 90-day trend. Use --since flag on all git/gh commands.
2. Measure Stocks
Stocks are things that accumulate. Measure current level + trend.
| Stock | How to measure | Healthy signal |
|---|
| Backlog | gh issue list --state open count | Stable or shrinking |
| Open PRs | gh pr list --state open count + age | < 5 open, oldest < 3 days |
| Open bugs | gh issue list --label bug --state open count | Stable or shrinking |
| Test count | Test runner --list or dry-run | Growing with codebase |
| Deploy count | gh run list with deploy workflow, or git tags | Weekly+ |
Trend indicators: Compare current 30-day window to previous 30-day window.
- ▲ growing (stock increasing)
- ▼ shrinking (stock decreasing)
- ─ stable (within 10% variance)
3. Measure Flows
Flows change stocks. Measure rate + balance.
| Flow | How to measure | What it tells you |
|---|
| Stories in | Issues created per week | Demand on the system |
| Stories out | PRs merged per week | Throughput |
| Cycle time | PR open → merge duration (median) | How fast work moves |
| Review time | PR open → first review (median) | Bottleneck indicator |
| Bug inflow | Bug issues created per week | Quality signal |
| Bug outflow | Bug issues closed per week | Fix rate |
| Deploy frequency | Deploys per week/month | Delivery cadence |
Balance check for each stock:
- Inflow > outflow → stock accumulates → system backing up
- Inflow < outflow → stock drains → system clearing
- Inflow ≈ outflow → stable
4. Assess Feedback Loops
Identify which loops are working and which are broken.
Balancing loops (self-correcting):
| Loop | Working | Broken |
|---|
| CI gate | CI fails → dev fixes → CI passes | CI fails → ignored, merged anyway |
| Code review | Review catches issues → dev fixes → quality maintained | Reviews rubber-stamped or stuck for days |
| Bug triage | Bug found → prioritized → fixed | Bugs accumulate, never triaged |
| Test failures | Test fails → investigate → fix code or test | Tests disabled, skipped, or ignored |
Reinforcing loops (amplifying):
| Loop | Working | Broken |
|---|
| Test coverage | Good tests → catch bugs → write more tests | No tests → bugs escape → "tests don't help" |
| Documentation | Good docs → agents work well → docs updated | Thin docs → agent rework → "docs don't help" |
| Small batches | Small PRs → fast review → more small PRs | Big PRs → slow review → bigger PRs |
Evidence-based assessment: Don't guess. Check CI pass rate (from gh run list), review turnaround (from PR data), bug trends (from issue data).
5. Measure Complexity Signals
Track whether the codebase is getting harder to work with over time. Based on Ousterhout's three symptoms of complexity — all derived from git data.
| Signal | What to measure | How | Concern threshold |
|---|
| Change amplification | Median files per commit (30d vs 90d) | git log --shortstat | Trending up |
| Shotgun surgery | % of commits touching 5+ files across 3+ directories | git log --shortstat + git show --name-only | > 20% of commits |
| Cognitive load | Top 5 most-changed files in 30d — flag any that are also among the largest | git log --name-only + file sizes | Large files with high churn |
| Unknown unknowns | % of merged PRs where no test file was changed | gh pr list --state merged + diff per PR | Trending up |
Present as a compact table with one interpretation line summarizing the overall complexity trend (accumulating / stable / improving).
If complexity is accumulating, feed into Diagnosis with specific interventions: split a god file, add tests to a hot path, extract a module.
6. Diagnose and Prescribe
For each problem found, follow the pattern:
Diagnosis: [what's sick]
Evidence: [data that proves it]
Impact: [how it slows delivery or hurts quality]
Rx: [cheapest intervention]
Prioritize by: most impact for least effort.
Common diagnoses:
- Stocks accumulating → find the bottleneck flow
- Slow cycle time → usually review time or CI time
- Broken feedback loop → identify who/what stopped responding to the signal
- No feedback loop → suggest creating one (tests, CI gate, review process)
7. Write Output
Write to .tap/system-health.md using the template in references/system-health-template.md.
If prior .tap/system-health.md exists, compare trends. Call out what improved and what worsened since last measurement.
Human mode: Walk through findings. Start with the headline ("your system is healthy / has 2 problems / is backing up"). Show the data. Explain the diagnosis. Propose the cheapest fix. Ask: "Want to dig into any of these?"
Agent mode: Write .tap/system-health.md silently. If run as part of a /retrospective, feed findings into the retro.
Wire discoverability
.tap/system-health.md is only read by agents that know it exists — CLAUDE.md is the only file loaded automatically. After writing, check the repo's CLAUDE.md for a .tap/ context-index line:
- Index line exists → make sure it mentions
system-health.md (delivery health check-in); append if missing.
- No index line → add one (show the diff, write on confirm):
Durable project context lives in .tap/ — system-health.md (delivery health check-in)[, plus any other .tap/ files present]. Read the relevant file before deciding in that area.
- No CLAUDE.md → tell the user the artifact is invisible to agents until something references it; offer a minimal CLAUDE.md containing just that pointer.
Boundaries
- Read-only — does NOT modify code, config, or process
- Does NOT assess code quality (that's CLAUDE.md / code review)
- Does NOT assess agent readiness (that's /tap-audit)
- Does NOT capture learnings (that's /retrospective)
- ONLY measures the system and diagnoses problems
- Data-driven — every claim backed by evidence from git/GitHub/CI
