people_analytics v1.0.0

name: people_analytics description: "People analytics a small team can run: fixed metric definitions for hiring, retention, and engagement, data quality checks before any calculation, a runnable CSV calculator, group size suppression, and honest reporting of what the numbers cannot say. Use when asked to measure turnover, retention, time to fill, cost per hire, first year attrition, eNPS, or engagement, to build an HR metrics report, or to check whether a people claim holds up."

People Analytics

Purpose

Help a small team answer three questions with numbers that hold up: how hard is it to hire, who is leaving and when, and how staff say work feels. Small teams have an advantage and a problem. The advantage is that they can check the raw rows by hand. The problem is that small counts swing hard, so a tidy percent can look certain when the fact underneath it is three people.

This skill ships fixed definitions, a checking order, and a calculator. Definitions come from published standards and official sources where they exist: cost per hire follows ANSI/SHRM 06001.2012, separation types match the US Bureau of Labor Statistics JOLTS split, and eNPS follows the Bain and Company promoter and detractor bands. Where no standard exists, the skill says so and makes the team write a local definition before reporting.

Workflow

1. Write the question and the decision before touching data. One sentence each. For example: turnover rose in support last quarter, and the decision is whether to change shift patterns or pay. A metric with no decision attached becomes decoration. If no decision would change based on the result, say that and stop.

1. Fix the population and the definitions. Write down who counts (full time, part time, contractors in or out, staff on leave), the period, the analysis date, and the exact definitions from references/metric-definitions.md. Cost per hire must list its cost lines. Turnover must state how average headcount was built. Changing a definition inside a trend breaks the trend, so log any change and restart the series or restate the old periods.

1. Run the data quality checks before calculating anything. Use the bundled calculator, which flags these automatically, and check the rest by hand:

• Duplicate employee IDs, missing start dates, and invalid dates.
• Exit date before start date, an exit date with no exit type, and an exit type with no exit date.
• Headcount reconciliation: headcount at period start, plus hires, minus separations, should equal headcount at period end. If it does not, find the missing or double counted rows first. Do not publish a rate off an unreconciled base.
• Missing teams, managers, or locations on a share of rows large enough to bend a group comparison. Report the missing share.
• Survey file: scores outside 0 to 10, duplicate responses where the survey was meant to be one per person, and groups named inconsistently across files. Report every flag in the output. A clean run with two known gaps is a usable report. A polished report that hid its gaps is not.

1. Compute the core set, no more. Use bin/people.py for CSV data, or the formulas in references/metric-definitions.md by hand or in a spreadsheet.

• Hiring: time to fill (mean and median), time to hire if candidate dates exist, cost per hire, offer acceptance rate.
• Retention: turnover overall and split into voluntary, involuntary, and other, plus tenure at exit and the share leaving in the first 90 days and first year.
• Engagement: response rate first, then eNPS or the engagement index, with respondent counts. Command that was tested on synthetic data:

python3 bin/people.py --employees employees.csv --reqs reqs.csv --survey survey.csv --survey-invited 12 --period-start 2025-01-01 --period-end 2025-12-31 --as-of 2025-12-31

Input formats are documented at the top of bin/people.py. Output is JSON with a data quality section, turnover by exit type and by team, hire cohorts, hiring figures when a requisitions file is given, and survey figures when a survey file is given.

1. Respect cohort maturity. First year attrition and cohort retention only count when every member of the cohort has had the full observation window. A cohort hired through December has not had a year by the following January. The calculator marks those cohorts not mature and returns no rate. Never fill an immature cell with the partial rate and never plot it as zero.

1. Suppress small groups before anyone sees a breakdown. Set a minimum group size as a written policy before the analysis. Five is a common floor for internal operational counts, ten is a safer floor for survey cuts where a person could be identified from a score and a team name. The calculator takes --min-group and suppresses rates below it. Below the floor, roll the group into a larger one or report the whole organisation only. This matters most for survey results, exit reasons, and any cut by a characteristic where one person could be picked out. Suppression is not hiding bad news. Note what was suppressed and why.

1. Check adverse impact separately, and carefully, when selection data is involved. If the analysis touches who gets hired, promoted, or let go by group, compute selection rates per group and the impact ratio: a group rate divided by the highest group rate. Under the Uniform Guidelines at 29 CFR 1607.4(D), a rate below four fifths (0.80) of the highest rate is generally treated as evidence of adverse impact. Treat that as a screen that triggers a proper review, not as a verdict and not as a clearance when the ratio sits above 0.80. Small groups make ratios swing on one decision. This check does not replace legal advice, and the employer stays responsible for tools bought from vendors as well as tools built in house.

1. Read the result in counts first, percents second. For each finding, state the count, the denominator, and then the percent. On a small team, 2 of 5 leaving is the fact, and 40 percent is a summary of it. Flag any group under 30 as noisy and avoid ranking teams or managers on small counts. Compare like with like: same period length, same definition, same population, and for seasonal work, the same period last year.

1. Separate what the data shows from why it happened. A rise in voluntary exits after a schedule change is a pattern that lines up in time. It is not proof the change caused the exits. Exit interviews, stay interviews, and manager notes are evidence too, with their own bias: leavers who agree to talk are not all leavers. Label each cause as observed, reported by staff, or a hypothesis. Name the test or the next data point that would settle a hypothesis before acting on it as fact.

1. Write the report using the Output Contract and references/report-template.md. Lead with the decision and the finding, not the dashboard. CIPD workforce reporting research makes the same point at board level: collecting people data is common, reviewing it with a clear narrative that ties it to priorities is the part that often goes missing. Keep the report short enough to be read in the meeting where the decision happens.

Output Contract

A people analytics report must contain:

• The question and the decision it feeds, in one sentence each.
• Definitions block: population, period, analysis date, source systems, average headcount method, separation definitions, survey items and scale, and every local definition flagged as local.
• Data quality section: each check from step 3, what was found, and what was fixed or left as a known gap.
• Core metrics with counts and denominators next to every percent or score: hiring, turnover by exit type, cohort results with immature cohorts marked not mature, and survey results with response rate.
• Group breakdowns only above the minimum group size, plus a note naming what was suppressed.
• Findings list: one sentence per finding, the numbers behind it, confidence (high, medium, low) with the reason, and a next action with an owner or an explicit no action note.
• Limits section: see Operating Rules. If a limit kills a finding, the finding comes out, not just the limit note.
• Follow up: which metric will be rechecked, on what date, to judge whether the action worked.

Operating Rules

• Never invent a benchmark. If you compare to an outside figure, name its source, year, population, and definition, and confirm the definitions match. A turnover benchmark built on a different separation definition is not a comparison.
• Never report a percent without its count and denominator when the group is under 500. On small teams, report counts first as the main figure.
• Never identify a person from analytics. No individual flight risk scores, no naming leavers or low scorers in a group report, and no survey cut small enough to point at one person. If a leader asks for that, refuse that cut and offer the larger group view.
• Never present eNPS or a single survey item as engagement itself. It is one advocacy question. It does not say why people scored as they did. Pair it with item level results or staff comments, reported in aggregate.
• Never claim causation from a before and after move alone. State the confounders you checked: pay changes, manager changes, layoffs, seasonality, a hiring surge that changed the mix, and definition changes.
• Never average away a mix shift without checking it. If overall turnover falls while it rises inside every team, the mix changed, not the teams. Segment first, then compare inside segments.
• Treat survey nonresponse as a finding. If response is low or lopsided by team or shift, the score describes the respondents. Say who is missing and what that could hide.
• Keep people data on a need to know basis. Work from the smallest extract that answers the question, keep named raw files out of shared folders, and delete working extracts when the report is done, per local policy and law. When law or policy is unclear for a new use of people data, pause that use and get advice before running it.
• If the data cannot support a conclusion, say so in plain words and name the data that would be needed. A no finding report that prevents a bad decision is a good report.