Some documents tell you how a thing works. A few tell you how it broke.
The Hard-Won badge marks the second kind. It means the document encodes something that actually bit someone — a specific failure, with the specific conditions that produced it and the specific thing that fixed it. Not a summary of the official documentation. Not a restatement of what the tool claims to do.
The distinction is worth a badge because it is the difference between guidance that saves you an afternoon and guidance that saves you the afternoon plus the three days you would have spent not realising the afternoon was the problem.
A document earns the badge when it clears the full review and also meets the editorial bar:
Documents that are useful but descriptive still get published. They just don't carry the badge. Two tiers, one library — the badge is a signal, not a gate.
These are orthogonal, deliberately. Hard-Won means the document encodes real experience. Unconfirmed means it may be out of date. A document can be both at once, and the best ones often are — the gotchas that bit hardest tend to be the oldest, and a hard-won lesson from eighteen months ago is still a lesson.
So the badge is never revoked by age. If a document is stale, the page says so, plainly and separately. You get both facts and you decide.
A maintainer, on the document, at review. It is not something a contributor can claim on their own submission — a badge everyone can award themselves is decoration. The field is rejected outright if a submission tries to set it, rather than quietly ignored, because an attempt to self-award is itself worth knowing about.
A stateful fake plus a control API, so a real app runs a full journey with no live calls — and the isolation you must build before the first run.
Four ratios used to score code quality, and four different reasons each one measured something other than what it claimed.
Two independent causes of a false-positive block, only one of which you can do anything about.
Getting a credential from its store into its destination without it ever appearing as text the assistant emits.
Why process-selection commands over-select silently, and the inspect-then-kill pattern that catches it.
Three checks that passed because they had no subjects, and why the fix is to make each one declare how many things it looked at.
Why a model correct op-by-op can still sound wrong, and the CPU hot paths a naive port leaves on the table.
Free platform subdomains are blocked as a category by security filters, so a subset of real users silently fails.
Wiring an updater keypair, a version manifest and a public bucket, and the flags that make uploads silently do nothing.
The certificate types, the notarisation flow, and the build setting that silently ships an unnotarised DMG.
A file format verified only by the reader you wrote is verified against your own assumptions.
Driving an interactive Windows session over SSH, and why testing as an admin proves nothing about permissions.
Seven invariants every document in this library must satisfy, and what happens to one that does not.
Drive interfaces by stable identity rather than pixels, in tiers, so tests are headless, deterministic and fan out.
Three ways a passing check reports success without ever being able to report anything else.
Three attempts to validate a scoring tool against human judgement, and why all three failing was evidence for the tool's premise rather than against it.
What to do when a tool built to outrank your judgement is wrong, given that overruling it destroys the only property it had.
An eligibility gate the sandbox does not enforce, a signature scheme that deviates from the spec it cites, and the webhook orderings that zero a live subscription.
Six ways a code scanner mistook writing about a practice for following it, and a seventh found inside the check built to prevent the other six.
Four cases where a description and the thing it described drifted apart, none of which was discoverable by reading the description again.
Two ways text scanning silently misses what it exists to find — soft line wraps, and identifiers in an unexpected form.