Skip to content

CLAUDE.md: add the HOT block — decisions that read as bugs - #171

Merged
rowan-claude merged 1 commit into
mainfrom
docs/hot-block
Jul 26, 2026
Merged

CLAUDE.md: add the HOT block — decisions that read as bugs#171
rowan-claude merged 1 commit into
mainfrom
docs/hot-block

Conversation

@rowan-claude

Copy link
Copy Markdown
Contributor

Coverage was 6/12 across the lane and the four flagship C libraries were the gap — the worst possible place for it, since these are the repos most likely to be reasoned about by someone who did not write them.

Distilled, not invented

Every item in the block was already documented somewhere in this file. The hot block is the part a stranger must read first, pulled to the top with file:line where the code says so itself. Nothing here is a new claim.

It answers one question: what in this repo looks like a defect and is not?

That is the exact failure this mechanism exists to stop. I recently reported netcode.rs's netcode-official crate name to Glenn as a defect — when it was a deliberate workaround already written down in that repo's hot block, which I had not read.

Things that would otherwise get "fixed"

  • flat linear scans chosen over a hash map, because an attacker controls the keys (source addresses) and could drive a hash into its worst case
  • release builds that deliberately carry no config validation — the caller is trusted by design
  • serialize macros that hide return false on purpose, because invalid data must abort before any attacker-bounded loop
  • debug asserts deliberately kept off the untrusted read path, so a hostile peer cannot crash a debug server

Glenn, emphatic: the per-repo hot block and the per-bud queue are "the most important things while you work."

Coverage was 6/12 across the lane and the four flagship libraries were the gap, which
is the worst possible place for it: these are the repos most likely to be reasoned
about by someone who did not write them.

DISTILLED, NOT INVENTED. Every item below was already documented somewhere in this
file; the hot block is the part a stranger must read FIRST, pulled to the top with
file:line where the code says so itself. Nothing here is a new claim.

The block answers one question: what in this repo looks like a defect and is not? That
is the failure this mechanism exists to stop -- I reported netcode.rs's
`netcode-official` crate name to Glenn as a defect when it was a deliberate workaround
already written down in that repo's block, which I had not read.

Examples of what would otherwise get "fixed": the flat linear scans that were chosen
OVER a hash map because an attacker controls the keys; release builds that deliberately
carry no config validation; serialize macros that hide `return false` on purpose;
debug asserts deliberately kept off the untrusted read path so a hostile peer cannot
crash a debug server.

Glenn, 2026-07-26, emphatic: the per-repo hot block and the per-bud queue are "the most
important things while you work."

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@rowan-claude
rowan-claude merged commit f039995 into main Jul 26, 2026
14 checks passed
@rowan-claude
rowan-claude deleted the docs/hot-block branch July 26, 2026 19:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant