From bd9c95d53058508d4ec228ba075ea859eccc2e98 Mon Sep 17 00:00:00 2001 From: Mathias Fredriksson Date: Mon, 15 Dec 2025 11:31:34 +0000 Subject: [PATCH 1/6] docs: add document for AI agents (AGENTS.md) --- AGENTS.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..624977c5 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,105 @@ +# Agents + +This document helps AI agents work effectively in this codebase. It explains the philosophy, patterns, and pitfalls behind the code, so you can make good decisions on any task, not just scenarios explicitly covered. Apply these principles while reading the code for specifics. + +## Philosophy + +This is a minimal, idiomatic WebSocket library. Simplicity is a feature. Before adding code, consider whether it's necessary. Before adding a dependency, don't; tests requiring external packages are isolated in `internal/thirdparty`. + +## Research + +**Read the issue carefully.** Before designing a solution, verify you understand what's actually being requested. Restate the problem in your own words. A solution to the wrong problem wastes everyone's time. + +**Understand the protocol first.** Code comments reference RFC 6455 (WebSocket), RFC 7692 (compression), and RFC 8441 (HTTP/2). When behavior seems odd, check the RFC section cited nearby. + +**Trace from public API inward.** Start with `Accept` (server) or `Dial` (client), then follow to `Conn`, then to `Reader`/`Writer`. The internal structure follows these paths. + +**Read tests for intent.** Tests often reveal why code exists. The autobahn-testsuite (`autobahn_test.go`) validates protocol compliance; if you're unsure whether behavior is correct, that's the authority. + +**Check both platforms.** Native Go files have `//go:build !js`. WASM lives in `ws_js.go` (imports `syscall/js`). They have the same API but different implementations. WASM wraps browser APIs and cannot control framing, compression, or masking, so don't try to implement those features there. + +**Search exhaustively when modifying patterns.** When changing how something is done in multiple places, grep for all instances. Missing one creates inconsistent behavior. + +## Making Changes + +**Every change needs a reason.** Don't reword comments, rename variables, or restructure code without justification. If you can't articulate why a change improves things, don't make it. + +**Understand before changing.** Research the code you're modifying. Trace the call paths, read the tests, check both platforms. A change with good intentions but incomplete understanding can break things in ways you won't notice. + +**Ask for clarification rather than assuming.** If requirements are ambiguous or you're unsure how something should work, stop and ask. A wrong assumption can waste more time than a quick question. + +**Iterate, don't pivot.** When feedback identifies a problem, fix that problem. Don't discard everything and start over with a different approach. Preserve what's working; adjust what isn't. + +**Verify examples work.** Trace through usage examples as if writing real code. If an example wouldn't compile, the design is wrong. + +**Don't delete existing comments.** Comments that explain non-obvious behavior preserve important context about why code works a certain way. If a comment seems wrong, verify before removing. + +**Check if it already exists.** Before proposing new API, read existing function signatures, return values, and doc comments. The feature might already be there. + +**Ask: does this need to exist?** The library stays small by saying no. A feature that solves one user's problem but complicates the API for everyone is not worth it. + +**Ask: is this the user's job or the library's job?** The library handles protocol correctness. Application-level concerns (reconnection, auth, message routing) belong in user code. + +**Ask: what breaks if I'm wrong?** Context cancellation closes connections. Pooled objects must be returned. Locks must respect context. These invariants exist because violating them causes subtle bugs. + +## Code Style + +Follow Go conventions: [Effective Go](https://go.dev/doc/effective_go), [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments), and [Go Proverbs](https://go-proverbs.github.io/). Be concise, declarative, and factual. + +Never use emdash. Use commas, semicolons, or separate sentences. + +**Doc comments** start with the name and state what it does. Put useful information where users make decisions (usually the constructor, not methods). + +**Inline comments** are terse. Prefer end-of-line when short enough. + +**Explain why, not what.** The code shows what it does; comments should explain reasoning, non-obvious decisions, or edge cases. + +**Wrap comments** at ~80 characters, continuing naturally at word boundaries. Don't put each sentence on its own line. + +**Avoid:** + +- Tautologies and redundant explanations the code already conveys +- Filler phrases: "Note that", "This is because", "It should be noted" +- Hedging: "basically", "actually", "really" + +## Key Invariants + +**Always read from connections.** Control frames (ping, pong, close) arrive on the read path. A connection that never reads will miss them and misbehave. `CloseRead` exists for write-only patterns. + +**Pooled objects must be returned.** `flate.Writer` is ~1.2MB. Leaking them causes memory growth. Follow `get*()` / `put*()` patterns; return on all paths including errors. + +**Locks must respect context.** The `mu` type in `conn.go` unblocks when context cancels or connection closes. Using `sync.Mutex` for user-facing operations would block forever on stuck connections. + +**Reads and writes are independent.** They have separate locks (`readMu`, `writeFrameMu`) and can happen concurrently. Don't create unnecessary coupling between them. + +**Masking is asymmetric.** Clients mask payloads; servers don't. The mask is applied into the bufio.Writer buffer, not in-place on source bytes. + +## Testing + +**Protocol compliance:** run autobahn tests with `AUTOBAHN=1 go test`. Some tests are intentionally skipped (UTF-8 validation adds overhead without value; `requestMaxWindowBits` is unimplemented due to `compress/flate` limitations). + +**Frame-level correctness:** compare wire bytes. When two implementations disagree, capture the bytes and check against the RFC. + +**WASM compatibility:** API changes need both implementations. Test that method signatures match. + +**Test style:** prefer table-driven tests and simple want/got comparison. + +## Commits and PRs + +Use conventional commits: `type(scope): description`. Scope is optional but include it when changes are constrained to a single file or directory. + +**Choose precise verbs:** `add` (new functionality), `fix` (broken behavior), `prevent` (undesirable state), `allow` (enable action), `handle` (edge cases), `improve` (performance/quality), `use` (change approach), `skip` (bypass), `remove` (delete), `rewrite` (substantial rework). + +**Commit messages explain why.** State what was wrong with previous behavior, why it mattered, and why this solution was chosen. One to three sentences. Keep the tone neutral; don't editorialize. + +**PR descriptions are for humans.** Don't fill out a template with "Summary", "Background", "Changes" headers. Don't restate the diff. Explain what reviewers can't see: the why, alternatives considered, and tradeoffs made. Show evidence (logs, benchmarks, screenshots). Be explicit about what the PR doesn't do. + +**Link issues:** `Fixes #123` (PR resolves it), `Refs #123` (related), `Updates #123` (partial progress). + +## RFC References + +- RFC 6455: The WebSocket Protocol +- RFC 7692: Compression Extensions for WebSocket (permessage-deflate) +- RFC 8441: Bootstrapping WebSockets with HTTP/2 + +Section numbers in code comments refer to these RFCs. From f19b67d7bda26b737cb895148599965b7c9175a7 Mon Sep 17 00:00:00 2001 From: Mathias Fredriksson Date: Tue, 16 Dec 2025 14:13:31 +0000 Subject: [PATCH 2/6] docs: teach how to plan --- AGENTS.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 624977c5..f9a96bff 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,6 +6,18 @@ This document helps AI agents work effectively in this codebase. It explains the This is a minimal, idiomatic WebSocket library. Simplicity is a feature. Before adding code, consider whether it's necessary. Before adding a dependency, don't; tests requiring external packages are isolated in `internal/thirdparty`. +## Planning + +When asked to plan, write to `PLAN.md`. Write for someone else, not yourself; don't skip context you already know. Research deeply before proposing solutions. + +**Follow references.** If there's a link, issue, or RFC citation, read it. Document important findings in a research section so the implementer can verify. + +**Focus on what and why.** Provide enough context for the implementer to understand the problem and constraints. Code examples can illustrate intent, but don't over-specify; leave room for the implementer to find a better approach. + +**Tell them where to look.** Point to specific files, functions, or line numbers. Make claims verifiable. + +**Review before finishing.** Make a final pass to check for gaps in research or unanswered questions, then update the document. + ## Research **Read the issue carefully.** Before designing a solution, verify you understand what's actually being requested. Restate the problem in your own words. A solution to the wrong problem wastes everyone's time. From d62ea10ca1ae2eee5e2cbcc1972bdcd2e9f8a8d7 Mon Sep 17 00:00:00 2001 From: Mathias Fredriksson Date: Tue, 16 Dec 2025 16:30:58 +0000 Subject: [PATCH 3/6] add .gitignore --- .gitignore | 1 + 1 file changed, 1 insertion(+) create mode 100644 .gitignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..d1941b1c --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +PLAN.md From c8bb8441a012ddfed5336e9252a3e48dc1126438 Mon Sep 17 00:00:00 2001 From: Mathias Fredriksson Date: Tue, 16 Dec 2025 19:36:27 +0000 Subject: [PATCH 4/6] docs: fix overeager agents --- AGENTS.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index f9a96bff..8ecf361f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,6 +20,8 @@ When asked to plan, write to `PLAN.md`. Write for someone else, not yourself; do ## Research +**If you were given a link, read it now.** Do not explore code, do not pass go. Fetch the linked issue or document first. Summarize what it asks for before proceeding. If you cannot restate the problem, you are not ready to solve it. + **Read the issue carefully.** Before designing a solution, verify you understand what's actually being requested. Restate the problem in your own words. A solution to the wrong problem wastes everyone's time. **Understand the protocol first.** Code comments reference RFC 6455 (WebSocket), RFC 7692 (compression), and RFC 8441 (HTTP/2). When behavior seems odd, check the RFC section cited nearby. @@ -34,6 +36,8 @@ When asked to plan, write to `PLAN.md`. Write for someone else, not yourself; do ## Making Changes +**Did you do your research?** If you haven't read the linked issue, traced the code paths, and verified your understanding, stop. Go back to Research. + **Every change needs a reason.** Don't reword comments, rename variables, or restructure code without justification. If you can't articulate why a change improves things, don't make it. **Understand before changing.** Research the code you're modifying. Trace the call paths, read the tests, check both platforms. A change with good intentions but incomplete understanding can break things in ways you won't notice. From 8b11445db5d55efd12a0ab5b970aa9ebe8ce822b Mon Sep 17 00:00:00 2001 From: Mathias Fredriksson Date: Tue, 16 Dec 2025 19:56:25 +0000 Subject: [PATCH 5/6] docs: how to name --- AGENTS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 8ecf361f..a40c14ed 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -72,6 +72,8 @@ Never use emdash. Use commas, semicolons, or separate sentences. **Wrap comments** at ~80 characters, continuing naturally at word boundaries. Don't put each sentence on its own line. +**Naming matters.** Before proposing a name, stop and review existing names in the file. A good name is accurate on its own and consistent in context. Ask: what would someone assume from this name? Does it fit with how similar things are named? + **Avoid:** - Tautologies and redundant explanations the code already conveys From 1522cbf1d469cd12a43ef548828bd2e55fbcdb97 Mon Sep 17 00:00:00 2001 From: Mathias Fredriksson Date: Fri, 9 Jan 2026 09:55:14 +0000 Subject: [PATCH 6/6] rewrite with gates --- AGENTS.md | 130 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 82 insertions(+), 48 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a40c14ed..93bf8d64 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,62 +1,105 @@ # Agents -This document helps AI agents work effectively in this codebase. It explains the philosophy, patterns, and pitfalls behind the code, so you can make good decisions on any task, not just scenarios explicitly covered. Apply these principles while reading the code for specifics. +This document helps AI agents work effectively in this codebase. It explains the philosophy, patterns, and pitfalls behind the code, so you can make good decisions on any task, not just scenarios explicitly covered. ## Philosophy -This is a minimal, idiomatic WebSocket library. Simplicity is a feature. Before adding code, consider whether it's necessary. Before adding a dependency, don't; tests requiring external packages are isolated in `internal/thirdparty`. +This is a minimal, idiomatic WebSocket library. Simplicity is a feature. -## Planning +Before adding code, articulate why it's necessary in one sentence. If you cannot justify the addition, it probably isn't needed. -When asked to plan, write to `PLAN.md`. Write for someone else, not yourself; don't skip context you already know. Research deeply before proposing solutions. +Before adding a dependency, don't. Tests requiring external packages are isolated in `internal/thirdparty`. -**Follow references.** If there's a link, issue, or RFC citation, read it. Document important findings in a research section so the implementer can verify. +## Workflow -**Focus on what and why.** Provide enough context for the implementer to understand the problem and constraints. Code examples can illustrate intent, but don't over-specify; leave room for the implementer to find a better approach. +Every task follows phases. Do not skip phases; if you realize you missed something, return to the appropriate phase. -**Tell them where to look.** Point to specific files, functions, or line numbers. Make claims verifiable. +**Making changes:** -**Review before finishing.** Make a final pass to check for gaps in research or unanswered questions, then update the document. +1. **Research** - Understand the problem and codebase before acting +2. **Plan** - Articulate your approach before implementing (when asked, or for complex changes) +3. **Implement** - Make changes in small, verifiable steps +4. **Verify** - Confirm correctness using external tools + +For trivial changes (typo fixes, comment updates), an abbreviated workflow is acceptable. ## Research -**If you were given a link, read it now.** Do not explore code, do not pass go. Fetch the linked issue or document first. Summarize what it asks for before proceeding. If you cannot restate the problem, you are not ready to solve it. +Research in sequential passes. Each pass has one focus. Don't skip ahead to code until you've completed the earlier passes. + +**Pass 1: Read the issue.** If you were given a link, read it now. Do not explore code, do not pass go. Fetch the linked issue or document first. Summarize what it asks for. If you cannot restate the problem, you are not ready to proceed. + +**Pass 2: Read linked references.** Follow every link in the issue: related issues, RFCs, external docs. Document what you learn. Code comments reference RFC 6455 (WebSocket), RFC 7692 (compression), and RFC 8441 (HTTP/2). + +**Pass 3: Trace the code.** Start from public API inward: `Accept` (server) or `Dial` (client) → `Conn` → `Reader`/`Writer`. Read tests for intent; the autobahn-testsuite (`autobahn_test.go`) validates protocol compliance. + +**Pass 4: Check both platforms.** Native Go files have `//go:build !js`. WASM lives in `ws_js.go`. Same API, different implementations. WASM wraps browser APIs and cannot control framing, compression, or masking. + +**Pass 5: Search exhaustively.** If the change affects a pattern used in multiple places, grep for all instances. Missing one creates inconsistent behavior. + +**Pass 6: Document unknowns.** List what you still don't know. Unknown unknowns become known unknowns when you ask "what am I still unsure about?" + +**After all passes:** Can you restate the problem in your own words? If not, return to Pass 1. Gaps in earlier passes will cause problems later. + +## Plan + +When asked to plan, write to `PLAN.md`. Write for someone else, not yourself; don't skip context you already know. + +**Pass 1: Document research.** Summarize what you learned in Research. Follow every reference; document findings so the implementer can verify. If the research section is empty, you haven't researched enough. + +**Pass 2: Consider approaches.** For non-trivial problems, enumerate at least two approaches. For each, note: what would change, what could go wrong, what's the tradeoff. -**Read the issue carefully.** Before designing a solution, verify you understand what's actually being requested. Restate the problem in your own words. A solution to the wrong problem wastes everyone's time. +**Pass 3: Detail the chosen approach.** Explain what and why, not step-by-step how. Point to specific files, functions, line numbers. Make claims verifiable. Leave room for the implementer to find a better solution. -**Understand the protocol first.** Code comments reference RFC 6455 (WebSocket), RFC 7692 (compression), and RFC 8441 (HTTP/2). When behavior seems odd, check the RFC section cited nearby. +**Pass 4: List open questions.** What's still unclear? What assumptions are you making? What would change your approach? -**Trace from public API inward.** Start with `Accept` (server) or `Dial` (client), then follow to `Conn`, then to `Reader`/`Writer`. The internal structure follows these paths. +**After all passes:** Review from the implementer's perspective. Could they start work with only this document? If not, add what's missing. -**Read tests for intent.** Tests often reveal why code exists. The autobahn-testsuite (`autobahn_test.go`) validates protocol compliance; if you're unsure whether behavior is correct, that's the authority. +## Implement -**Check both platforms.** Native Go files have `//go:build !js`. WASM lives in `ws_js.go` (imports `syscall/js`). They have the same API but different implementations. WASM wraps browser APIs and cannot control framing, compression, or masking, so don't try to implement those features there. +Implement in sequential passes. Don't write code until you've completed the verification passes. -**Search exhaustively when modifying patterns.** When changing how something is done in multiple places, grep for all instances. Missing one creates inconsistent behavior. +**Pass 1: Verify understanding.** Did you do your research? Can you state your approach in one sentence? If requirements are ambiguous, stop and ask. A wrong assumption wastes more time than a quick question. -## Making Changes +**Pass 2: Check scope.** Does this need to exist? Check if it already exists in the API. Is this the library's job or the user's job? The library handles protocol correctness; application concerns (reconnection, auth, routing) belong in user code. -**Did you do your research?** If you haven't read the linked issue, traced the code paths, and verified your understanding, stop. Go back to Research. +**Pass 3: Check invariants.** Walk through Key Invariants before writing code: +- Reads: Will something still read from the connection? +- Pools: Will pooled objects be returned on all paths? +- Locks: Are you using context-aware `mu`, not `sync.Mutex`? +- Independence: Are you coupling reads and writes unnecessarily? -**Every change needs a reason.** Don't reword comments, rename variables, or restructure code without justification. If you can't articulate why a change improves things, don't make it. +**Pass 4: Implement.** Make the change. Every change needs a reason; if you can't articulate why it improves things, don't make it. Preserve existing comments unless you can prove they're wrong. -**Understand before changing.** Research the code you're modifying. Trace the call paths, read the tests, check both platforms. A change with good intentions but incomplete understanding can break things in ways you won't notice. +**Pass 5: Verify examples.** Trace through usage examples as if writing real code. If an example wouldn't compile, the design is wrong. Check edge cases: what happens on error? On cancellation? -**Ask for clarification rather than assuming.** If requirements are ambiguous or you're unsure how something should work, stop and ask. A wrong assumption can waste more time than a quick question. +**After all passes:** If feedback identifies a problem, fix that specific problem. Don't pivot to a new approach without articulating what failed and why the new approach avoids it. -**Iterate, don't pivot.** When feedback identifies a problem, fix that problem. Don't discard everything and start over with a different approach. Preserve what's working; adjust what isn't. +## Verify -**Verify examples work.** Trace through usage examples as if writing real code. If an example wouldn't compile, the design is wrong. +Verify using external signals. Self-assessment is unreliable; these tools are the ground truth. -**Don't delete existing comments.** Comments that explain non-obvious behavior preserve important context about why code works a certain way. If a comment seems wrong, verify before removing. +**Pass 1: Run tests.** `go test ./...` must pass. If tests fail, return to Research to understand why, not to Implement to "fix" it. -**Check if it already exists.** Before proposing new API, read existing function signatures, return values, and doc comments. The feature might already be there. +**Pass 2: Run vet.** `go vet ./...` must report no issues. -**Ask: does this need to exist?** The library stays small by saying no. A feature that solves one user's problem but complicates the API for everyone is not worth it. +**Pass 3: Check platforms.** Code must compile on both native Go and WASM. API changes need both implementations; test that method signatures match. -**Ask: is this the user's job or the library's job?** The library handles protocol correctness. Application-level concerns (reconnection, auth, message routing) belong in user code. +**Pass 4: Protocol compliance.** For protocol changes, run `AUTOBAHN=1 go test`. Compare wire bytes when implementations disagree; check against the RFC. -**Ask: what breaks if I'm wrong?** Context cancellation closes connections. Pooled objects must be returned. Locks must respect context. These invariants exist because violating them causes subtle bugs. +**After all passes:** If any pass fails, fix the issue and restart from Pass 1. Don't consider a change complete until all passes succeed. + +## When Uncertain + +If confidence is low or requirements are ambiguous: + +1. State what you're uncertain about +2. Identify what information would resolve the uncertainty +3. Gather that information or ask for clarification + +Do not proceed with low-confidence assumptions. + +For complex changes, approach from multiple angles. If two approaches give different answers, that discrepancy demands resolution before proceeding. ## Code Style @@ -64,21 +107,20 @@ Follow Go conventions: [Effective Go](https://go.dev/doc/effective_go), [Go Code Never use emdash. Use commas, semicolons, or separate sentences. -**Doc comments** start with the name and state what it does. Put useful information where users make decisions (usually the constructor, not methods). +**Doc comments** start with the name and state what it does. Structure: `// [Name] [verb]s [what]. [Optional: when/why to use it].` Put useful information where users make decisions (usually the constructor, not methods). **Inline comments** are terse. Prefer end-of-line when short enough. **Explain why, not what.** The code shows what it does; comments should explain reasoning, non-obvious decisions, or edge cases. -**Wrap comments** at ~80 characters, continuing naturally at word boundaries. Don't put each sentence on its own line. - -**Naming matters.** Before proposing a name, stop and review existing names in the file. A good name is accurate on its own and consistent in context. Ask: what would someone assume from this name? Does it fit with how similar things are named? +**Wrap comments** at ~80 characters, continuing naturally at word boundaries. -**Avoid:** +**Naming matters.** Before proposing a name, stop and review existing names in the file. Ask: what would someone assume from this name? Does it fit with how similar things are named? A good name is accurate on its own and consistent in context. -- Tautologies and redundant explanations the code already conveys -- Filler phrases: "Note that", "This is because", "It should be noted" -- Hedging: "basically", "actually", "really" +**Comment content:** +- Add information beyond what the code shows (not tautologies) +- State directly: "Returns X" (not "Note that this returns X") +- Drop filler: "basically", "actually", "really" add nothing ## Key Invariants @@ -88,29 +130,21 @@ Never use emdash. Use commas, semicolons, or separate sentences. **Locks must respect context.** The `mu` type in `conn.go` unblocks when context cancels or connection closes. Using `sync.Mutex` for user-facing operations would block forever on stuck connections. -**Reads and writes are independent.** They have separate locks (`readMu`, `writeFrameMu`) and can happen concurrently. Don't create unnecessary coupling between them. +**Reads and writes are independent.** They have separate locks (`readMu`, `writeFrameMu`) and can happen concurrently. Keep them decoupled. **Masking is asymmetric.** Clients mask payloads; servers don't. The mask is applied into the bufio.Writer buffer, not in-place on source bytes. -## Testing - -**Protocol compliance:** run autobahn tests with `AUTOBAHN=1 go test`. Some tests are intentionally skipped (UTF-8 validation adds overhead without value; `requestMaxWindowBits` is unimplemented due to `compress/flate` limitations). - -**Frame-level correctness:** compare wire bytes. When two implementations disagree, capture the bytes and check against the RFC. - -**WASM compatibility:** API changes need both implementations. Test that method signatures match. - -**Test style:** prefer table-driven tests and simple want/got comparison. - ## Commits and PRs Use conventional commits: `type(scope): description`. Scope is optional but include it when changes are constrained to a single file or directory. **Choose precise verbs:** `add` (new functionality), `fix` (broken behavior), `prevent` (undesirable state), `allow` (enable action), `handle` (edge cases), `improve` (performance/quality), `use` (change approach), `skip` (bypass), `remove` (delete), `rewrite` (substantial rework). -**Commit messages explain why.** State what was wrong with previous behavior, why it mattered, and why this solution was chosen. One to three sentences. Keep the tone neutral; don't editorialize. +**Before writing the commit message**, articulate what was wrong with the previous behavior and why this change fixes it. The commit message captures this reasoning. + +**Commit messages explain why.** State what was wrong, why it mattered, and why this solution was chosen. One to three sentences. Keep the tone neutral. -**PR descriptions are for humans.** Don't fill out a template with "Summary", "Background", "Changes" headers. Don't restate the diff. Explain what reviewers can't see: the why, alternatives considered, and tradeoffs made. Show evidence (logs, benchmarks, screenshots). Be explicit about what the PR doesn't do. +**PR descriptions are for humans.** Explain what reviewers can't see: the why, alternatives considered, and tradeoffs made. Show evidence (logs, benchmarks, screenshots). Be explicit about what the PR doesn't do. **Link issues:** `Fixes #123` (PR resolves it), `Refs #123` (related), `Updates #123` (partial progress).