team_health_pulse v1.0.0

name: "team_health_pulse" description: "Reading team health from real signals: combine anonymous survey results, coded one on one themes, meeting behaviour, workload, and attrition indicators into a short risk list where each risk has an owner and an intervention, scored with a runnable tool, then recheck after the change. Use when asked for a team health check, a team pulse read, why a team is struggling, whether an intervention worked, or how to combine engagement survey, meeting, workload, and turnover signals for one team."

Team Health Pulse

Purpose

Turn five weak signals into one clear read. A survey alone is opinion, meeting behaviour alone is a snapshot, and attrition alone arrives too late. Put together, coded by theme, they show which problems are real, which are noise, and whether a fix moved anything. This skill ships a scoring tool and a worked read on a sample team, so the method can be run, checked, and repeated, not just described.

Workflow

1. Fix the unit and the window before touching data. One named team, one pulse window (the survey period, the meetings observed, the trailing months for attrition), and the date of the last pulse. A pulse that mixes teams or windows cannot be trended and cannot be trusted.

1. Gather one signal set per family, using references/signals-and-sources.md for what counts and how to score it. Families are survey, one_on_one, meetings, workload, and attrition. Score every signal 0 to 100, higher is healthier, and invert raw counts where high is bad. Write the inversion into the label. Aggregate only: no named survey answers, no quoted one on one notes, no persons hours on a chart.

1. Protect small groups before scoring. Do not report a cut with fewer than 5 respondents, and use 7 to 10 for open text or sensitive topics. Roll small groups up and say so. The tool enforces the floor: any signal with n below --min-n is listed as suppressed and left out of every score.

1. Build the CSV in the shape of references/sample-team.csv: signal_id, family, theme, label, score, prev_score, weight, n, source. Themes are the joining key across families, for example workload, safety, clarity, support, recognition, growth, retention. Keep weights at 1 unless a signal clearly carries more evidence, and write the reason in the read when you change one.

1. Score it with the bundled tool and read the exit code. Code 1 means red families or convergent themes are present, which is a finding, not a tool failure.

bash
   python3 scripts/pulse.py score --input references/sample-team.csv
   python3 scripts/pulse.py score --input references/sample-team.csv --format json
   

Bands are 70 and up green, 50 to 69 amber, below 50 red. A drop of 10 or more against the last pulse is worsening, 5 to 9 is watch. Bands and trend cut offs are this skills planning heuristics, not published standards, and the read must say so once.

1. Collapse the risk list by theme before writing anything. The tool flags a theme as convergent when it is amber or red in two or more families. Convergent themes lead the read. A lone red with no second family behind it goes on the watch list unless its score or drop is extreme. Three findings is a good size for a read. Eight risks pasted raw is a data dump, not a read.

1. Assign one intervention per lead risk from references/interventions.md, with a named owner and a recheck date. Cap active interventions at two or three. Each intervention names the signal that should move if it works. An intervention with no target signal cannot be rechecked and does not belong in the plan.

1. Recheck on the date set, with the same signals, the same scoring, and the same thresholds. Run the recheck comparison and report it straight, including what got worse.

bash
   python3 scripts/pulse.py recheck --before references/sample-team.csv --after references/sample-team-followup.csv
   

A move of 5 or more points counts as a real move in the tool. That cut off is a heuristic. Report cleared reds, new reds, and any target signal that stayed red after a big improvement, all three, because each one changes what happens next.

Output Contract

Deliver a team health pulse read containing, at minimum:

• Header: team, pulse window, survey response count, meetings observed, date of last pulse, and any group that was rolled up or suppressed for size.
• The family table: score, band, trend, and delta for survey, one_on_one, meetings, workload, and attrition, plus the overall score, with a one line note that bands and trend cut offs are heuristics.
• The findings: at most three lead risks, each stated as a theme, the families and signals behind it with their scores, and why it ranks where it ranks. Convergent themes come before lone signals.
• The watch list: red or falling signals that did not make the lead list, with the reason they are being watched instead of acted on now.
• The intervention plan: one intervention per lead risk, owner, start date, target signal, and recheck date.
• At a recheck: before and after per target signal with the tool verdict (improved, flat, worse), cleared reds, new reds, what the result says about each intervention in plain words, and the next intervention list.
• A worked example of this contract, with every number produced by the tool, is in references/worked-read.md.

Operating Rules

• Work at team level only. Never build an individual risk, flight, or health score for a named person from pulse data, and never use a pulse as a performance rating for a team or a lead. Spotify published the same warning for its health check: a support tool, not a judgement tool, and teams must have no reason to game it.
• Treat survey honesty as the asset everything else depends on. If a result is ever used to punish a team or a person, say plainly that future pulses from that team will read better and mean less, and do not pretend the next score is comparable.
• Use burnout language for the work system, never as a diagnosis of a person. The World Health Organization classifies burn out in ICD-11 as an occupational phenomenon, not a medical condition. A person in distress gets a human conversation and real support, not a row in the CSV.
• Do not copy Gallups Q12 items into a survey. They are Gallup proprietary material. Write plain items on the same themes, license the instrument, or use Edmondsons published seven item safety scale with its reverse scoring handled.
• Do not rank teams against each other from pulse scores. Different teams face different work and different honesty levels. A red team that reported honestly needs support first. Cross team reading is for shared themes, for example workload red in four teams at once, which points at the system above the teams.
• State what is missing. A pulse with no meeting observation is a survey read, a pulse with no attrition window is a snapshot, and a first pulse has no trend. Name the gap in the header instead of letting a clean table imply full coverage.
• Keep raw files restricted. Share the read widely inside the team and with its lead. Keep row level survey data, coded one on one theme sheets, and HR detail on a need to know basis.