A metric needs a recommendation to be actionable
A metric needs a recommendation to be actionable
Showing someone "complexity: 16" does almost nothing. They don't know if 16 is bad, how bad, or what to do about it. The number is a diagnosis with no prescription, and most people just learn to ignore it.
A metric earns its place on the screen when it comes with three things:
- A comparison. 16 against a guide of 15 reads differently than 16 against 10. Show the threshold and the delta, not the raw value alone.
- A cause. Where the number comes from — "mostly nested conditionals" — so the reader knows which lever to pull.
- A move. The concrete next step: extract the inner block, split by responsibility, break the PR here. Plain language, one action.
Why this keeps coming up
I hit this building the Review System Changes Skill. The first version listed cyclomatic complexity as a bare number next to each flagged function, and it was useless — a reviewer looking at "cx 16" has no idea whether to care. The fix was to have each flag carry a recommendation grounded in why it tripped: for cognitive complexity, name the nesting and say to extract it; for a long parameter list, suggest grouping into an options object. Same for the reviewability score — Hard isn't a verdict, it's a prompt to split.
The rule generalises past code metrics. Any dashboard number, lint warning, or health score has the same failure mode: if it doesn't tell you what to do, it becomes wallpaper. This is the numeric cousin of the deletion test in Operationally Useful Docs — if the reader can't act on it, it isn't pulling its weight.