The seven signals — what each wants, in what unit

Every need carries seven signals. Four are need-specific, asked or voted per need. Three are group-wide telemetry, written identically onto all 41 needs, so they say nothing about any one of them — which is why coverage counts the need-specific four only.

Source of truth (in hoen-assessment): apps/hoen-explorer/src/snapshots/normalisation.ts.

Need-specific — go in needs["<need-id>"]

Field	Scale	Direction	Where it comes from
survey	0–10	higher = healthier	Don't write this by hand. Supply questions instead and the rollup computes it. An inline value is only read when no question matched.
maturity	0–3	higher = healthier	SME self-rating in the workshop. Whole or half steps are normal.
spendRank	1–10, or a longer stack	inverted — 1 scores 0, the stack maximum scores ~100	Stack rank over current spend. Rank 1 = the most current spend is already going in, which the model reads as a live, funded gap. Getting this backwards inverts the signal. The default band is 10; a workshop stack that runs longer is fine and the group's own maximum is used instead.
spendAmount	any number	inverted by rank	Optional. Raw dollars. Used when every need in the file carries one and spendRank stays inside the 1–10 band — then the canonical stack rank replaces the rank column. Partial coverage is ignored; a stack running past 10 keeps spendRank spacing.
workshopDotVote	0–1	inverted — a need that soaked up votes scores low	Share of the workshop's dots that landed on this need. Dots mark where the experts think the problems are.

spendRank and workshopDotVote both invert, and that is the most common intake error. A need everyone voted for is a need in trouble, so it scores low — the same direction as every other signal, where 100 means healthy.

The spend stack: transcribe the park bucket too

This is the one place where writing down a rank you were told, rather than omitting it, is the correct move.

Facilitators stack all 41 needs and park the ones nobody discussed on a shared bottom rank, often with a leftover $1. The engine uses that shared bottom rank to detect what was never discussed and drop it from spend scoring altogether:

What the file carries	What the engine does
Every need has a spendAmount, and 2+ needs share the bottom rank at the same leftover amount	Needs above the leftover floor are scored; the parked tail is dropped
Ranks only, stack maximum ≤ 10	Every ranked need is scored
Ranks only, stack runs past 10	The shared bottom rank is treated as the park bucket and dropped

So transcribing only the funded top ten and omitting the rest is worse than useless: the other 31 needs default to rank 5.5, the stack maximum falls to 10, and 31 mid-stack allocations nobody ever made are scored as real. Before this rule existed, reading the parked tail as "well funded" made unspoken needs outscore each group's actual top priority.

Dot votes: share, not count

Given counts, divide by the total dots cast across all needs, so the values sum to roughly 1 for the group. A raw count — 7 — clamps to 1 and reads as "every dot landed here".

Group-wide telemetry — goes in rawMetrics

The rawMetrics block must be present or the file is rejected outright. Use {} when there is no telemetry — that is an honest empty block, not an error.

Field	Unit	Feeds	Notes
leadTimeHours	hours	CTP (0.6)	Commit to running in production. Curve is meaningful over ~1–60h.
deployPerDay	per day	CTP (0.4)	Scored against a target of one deploy per two active contributors per day — so it needs totalActiveContributors to mean anything.
totalActiveContributors	people	CTP	Defaults to 4 if absent, which will flatter a large group.
teamsCount	teams	CQA, QoS	Incident counts are compared per team. Absent = treated as one team, which will make a multi-team group look far worse.
changeFailPct	percent, 0–100	CQA (0.3)	Not a 0–1 fraction. Clamped to 0–20 by the curve.
recoveryTimeHours	hours	CQA (0.3) and QoS (0.15)	MTTR after a failed change. Note the model's measure table labels this in minutes; the snapshot field is hours.
incidentsLowPerMonth	per month	CQA (0.1)	Low-severity, divided by teamsCount.
incidentsMedHighPerMonth	per month	QoS (0.4)	Customer-affecting, divided by teamsCount.
waitTimePct	percent, 0–100	CTP (0.2)	Waiting duration ÷ total elapsed duration × 100, over a stated commitment-to-customer boundary. Steep between 60% and 85%. Absent on current intake — supply a measured or explicitly estimated reading as an override in the Assessment data cards.
releaseConfidence	0–10	CQA (0.3) and QoS (0.45)	How confident the team is a release lands cleanly. Higher is better. Manual until the Likert items are wired; absent on current intake, and its weight redistributes when missing.

Two traps worth repeating. Both produce a plausible score rather than an error:

• recoveryTimeHours is hours. A dashboard reporting MTTR in minutes needs dividing by 60. 45 minutes entered as 45 reads as nearly two days.
• changeFailPct is 0–100. An SDO dashboard reporting 0.12 becomes 12.

Wait-time provenance

The percentage is not reproducible without its collection context. Record:

• start and end boundary;
• date range and number of work items;
• included work types and exclusions;
• workflow states classified as active or waiting;
• waiting duration and total elapsed duration;
• any correction factor, its basis and who agreed it.

Prefer a same-group trend over a cross-group comparison. Different work types, workflow conventions and status discipline can make two identical percentages mean different things. A benchmark or target is not a missing reading and must not be entered as a raw override.

What happens when something is missing

Nothing errors. ingest fills the gap:

Missing	Filled with
survey (no matched question, no inline value)	5 / 10
maturity	1.5 / 3
spendRank	5.5
workshopDotVote	0.5
a telemetry field	the signal is scored from whatever fields remain; a signal with no fields at all is absent

A defaulted need scores like a measured one. Hence omit, never guess — an omission shows on the coverage meter, an invented 1.5 does not.