Team Health Reports

Team health reports aggregate squad-level data into a periodic assessment of how a squad is doing — not just what it's shipping, but how sustainable its delivery patterns are.

How Reports Are Generated

Health reports are produced by the TeamHealthJob, an Oban background job that runs on a configurable schedule (default: weekly).

The pipeline works like this:

TeamHealthJob triggers
    |
    v
Gather squad data for the reporting period
(commits, PR cycle times, velocity, cognitive load, dependency map)
    |
    v
LLM synthesis (Claude Sonnet)
Produces a structured health assessment from the raw data
    |
    v
Store report in database with timestamp

The LLM synthesis step is key — it doesn't just summarize numbers. It looks for patterns across multiple dimensions and produces a narrative assessment. For example, it might note that velocity increased but so did cognitive load, suggesting the squad is sprinting unsustainably.

Health Dimensions

Each report assesses the squad across several dimensions:

Dimension	What it measures
Delivery pace	Is the squad shipping at a consistent rate? Are there stalls or bursts?
Code quality signals	Ratio of commits with tests, error handling, clean patterns
Focus	How concentrated is the squad's work within its owned domains?
Collaboration health	PR review patterns, cross-squad dependencies, knowledge silos
Tech debt trajectory	Is the squad accumulating or reducing technical debt?
Risk exposure	Frequency of commits touching auth, payments, or data models without deep analysis

Each dimension receives a qualitative assessment rather than a numeric score — the goal is actionable insight, not a leaderboard.

Historical Tracking

Reports are stored with timestamps, so you can compare health across reporting periods. This makes it possible to:

• Track whether interventions (hiring, scope changes, process tweaks) actually improved squad health
• Spot gradual degradation before it becomes a crisis
• Correlate health changes with external events (reorgs, big launches, on-call rotations)

The health report page shows the current report alongside a timeline of previous reports for the same squad.

Route

Route	Description
/c/:slug/team-health	Team health dashboard with current and historical reports