Writing Security Notes That Age Well

Security notes are often written for the next hour: a triage call, a release decision, or a quick maintainer handoff. The better ones also work six months later.

The durable version is usually shorter, calmer, and more explicit.

Start with the claim

Lead with the thing you believe is true:

The session token remains valid after password reset.

Then attach the evidence:

Observed on commit 8f2c...
Route: POST /account/password
Expected: session invalidated
Actual: session accepted on GET /account/settings

Separate fact from judgment

Facts should be reproducible. Judgment should be labeled:

• Fact: the route accepted the old session after reset.
• Judgment: this likely increases account takeover impact.
• Unknown: whether production has an additional invalidation layer.

End with the next useful action

Good notes close with a specific next move: add a regression test, verify a config, ask for owner context, prepare a patch, or route sensitive details to coordinated disclosure.

That is how a note becomes part of the product record instead of just another message that gets lost.