Clarity Is a Product Decision

I recently reworked a set of Key Results for an internal documentation and workflow effort. The original KRs were percentage-based: reduce failed states by X%, improve completion rate by Y%. They looked rigorous. They had numbers in them. Nobody could tell you what they actually meant.

A percentage needs a stable denominator to mean anything, and the denominator here, the total number of relevant events, moved constantly depending on team activity, seasonality, and which parts of the system were even being exercised that week. So "reduce failed states by 20%" was quietly unfalsifiable. You could hit the number because the underlying activity dropped, or miss it while genuinely fixing the problem. Nobody would know which had happened.

I rewrote them as counts: number of dead ends encountered, number of stuck states, number of PR build loops. Auditable. A specific number, tied to a specific log, that a specific person could go pull and check. No interpretation required.

That's a small example, but it's the whole argument in miniature. The percentage version felt more precise because it had more decimal places. The count version was more precise because it was actually checkable. Clarity isn't about sounding rigorous. It's about whether someone else can verify you were right without asking you what you meant.

Ambiguity is comfortable for the person writing the spec because it defers every hard tradeoff to whoever implements it. "Improve reliability" doesn't require you to decide what reliability means, who's accountable when it's ambiguous, or what happens when two reasonable people disagree about whether it improved. A precise definition requires you to make those calls now, in front of stakeholders, where you might be wrong.

This is why vague specs survive review so easily. Nobody can object to something that hasn't actually claimed anything yet. The cost shows up three weeks later, in a standup, when two engineers have built against two different interpretations of the same sentence and neither is wrong according to what was written.

A PM's real job in that moment isn't to write more words. It's to have already made the decision that the words were hiding.

Being precise is riskier than being vague, and that's exactly why it's a product decision and not a writing exercise. A precise spec can be wrong in a way a vague one can't. You've committed to a definition, a threshold, an owner, and if you got any of those wrong, it's visible and attributable to you. Vagueness protects the author. Clarity exposes them.

That tradeoff is the actual job. Choosing to be specific about what "done" means, who's accountable when a metric is ambiguous, and what happens in the edge case nobody wants to think about is a decision you make on purpose. You know it costs you the safety of being impossible to pin down later.

The best specs I've written weren't the ones with the most detail. They were the ones where I'd already had the uncomfortable conversation, with myself or with a skeptical engineer, about what would happen if the easy interpretation and the hard interpretation diverged. Then I picked one, in writing, before anyone could quietly default to whichever was more convenient.

Clarity, in that sense, isn't downstream of the decision. It is the decision, just written down where people can hold you to it.