npm - claude-dev-env - Versions diffs - 1.39.0 → 1.41.0 - Mend

claude-dev-env 1.39.0 → 1.41.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (60) hide show

package/CLAUDE.md +1 -1
package/_shared/pr-loop/scripts/config/post_audit_thread_constants.py +10 -0
package/_shared/pr-loop/scripts/config/reviews_disabled_constants.py +8 -0
package/_shared/pr-loop/scripts/grant_project_claude_permissions.py +53 -3
package/_shared/pr-loop/scripts/post_audit_thread.py +298 -3
package/_shared/pr-loop/scripts/preflight.py +129 -2
package/_shared/pr-loop/scripts/reviews_disabled.py +59 -0
package/_shared/pr-loop/scripts/revoke_project_claude_permissions.py +68 -3
package/_shared/pr-loop/scripts/tests/test_grant_project_claude_permissions.py +1 -1
package/_shared/pr-loop/scripts/tests/test_post_audit_thread.py +194 -1
package/_shared/pr-loop/scripts/tests/test_preflight.py +41 -0
package/_shared/pr-loop/scripts/tests/test_reviews_disabled.py +36 -0
package/_shared/pr-loop/scripts/tests/test_revoke_project_claude_permissions.py +1 -1
package/agents/pr-description-writer.md +150 -52
package/docs/PR_DESCRIPTION_GUIDE.md +127 -64
package/hooks/_gh_pr_author_swap_utils.py +1211 -0
package/hooks/blocking/gh_body_arg_blocker.py +9 -6
package/hooks/blocking/gh_pr_author_enforcer.py +480 -0
package/hooks/blocking/gh_pr_author_restore.py +100 -0
package/hooks/blocking/pr_converge_bugteam_enforcer.py +170 -0
package/hooks/blocking/pr_description_enforcer.py +56 -23
package/hooks/blocking/test_gh_body_arg_blocker.py +25 -3
package/hooks/blocking/test_gh_pr_author_enforcer.py +1166 -0
package/hooks/blocking/test_gh_pr_author_restore.py +512 -0
package/hooks/blocking/test_gh_pr_author_swap_utils.py +910 -0
package/hooks/blocking/test_pr_converge_bugteam_enforcer.py +311 -0
package/hooks/blocking/test_pr_description_enforcer.py +69 -8
package/hooks/config/gh_pr_author_swap_constants.py +76 -0
package/hooks/config/pr_converge_bugteam_enforcer_constants.py +55 -0
package/hooks/config/pr_converge_bugteam_enforcer_state.py +67 -0
package/hooks/config/pr_description_enforcer_constants.py +19 -0
package/hooks/config/test_pr_description_enforcer_constants.py +82 -0
package/hooks/hooks.json +40 -0
package/hooks/lifecycle/pr_converge_bugteam_skill_tracker.py +204 -0
package/hooks/lifecycle/test_pr_converge_bugteam_skill_tracker.py +283 -0
package/hooks/session/gh_pr_author_session_cleanup.py +171 -0
package/hooks/session/test_gh_pr_author_session_cleanup.py +575 -0
package/hooks/test__gh_pr_author_swap_utils.py +333 -0
package/package.json +1 -1
package/skills/_shared/pr-loop/scripts/write_audit_outcomes.py +2 -2
package/skills/_shared/pr-loop/scripts/write_fix_outcomes.py +2 -2
package/skills/bugteam/SKILL.md +28 -10
package/skills/bugteam/reference/audit-contract.md +22 -0
package/skills/bugteam/reference/github-pr-reviews.md +1 -1
package/skills/bugteam/reference/team-setup.md +5 -0
package/skills/bugteam/scripts/bugteam_fix_hookspath.py +8 -2
package/skills/bugteam/scripts/bugteam_preflight.py +36 -2
package/skills/bugteam/scripts/test__claude_permissions_common.py +48 -0
package/skills/bugteam/scripts/test_bugteam_preflight.py +41 -0
package/skills/bugteam/scripts/test_claude_permissions_common.py +18 -10
package/skills/copilot-review/SKILL.md +16 -0
package/skills/findbugs/SKILL.md +35 -7
package/skills/monitor-open-prs/SKILL.md +2 -1
package/skills/pr-converge/SKILL.md +11 -3
package/skills/pr-converge/config/constants.py +3 -1
package/skills/pr-converge/reference/per-tick.md +17 -0
package/skills/pr-converge/reference/state-schema.md +36 -8
package/skills/pr-converge/scripts/check_bugbot_ci.py +113 -8
package/skills/pr-converge/scripts/test_check_bugbot_ci.py +312 -0
package/skills/qbug/SKILL.md +33 -8

package/agents/pr-description-writer.md CHANGED Viewed

@@ -1,87 +1,185 @@
 ---
 name: pr-description-writer
-description: "MANDATORY agent for writing PR descriptions, commit messages, and PR comments. Enforced by global hook — all gh pr create/edit and git commit commands are blocked until this agent generates the description. Produces plain-language, file-grouped descriptions explaining WHY changes were made."
+description: "MANDATORY agent for writing PR descriptions, commit messages, PR comments, and issue comments. Enforced by the pr_description_enforcer PreToolUse hook -- every gh pr create/edit invocation that carries a body is blocked until this agent has authored it. Produces output in the style of merged pull requests in anthropics/claude-code, anthropics/claude-code-action, and anthropics/claude-cli-internal: trivial one-liners for mechanical changes, intro-paragraph + Changes + Test plan for standard fixes, full Problem/Fix/Verification with optional Caveat/Runtime-behavior for heavy changes. Triggers: write a PR body, draft a PR description, author the commit message, comment on the PR, comment on the issue, prepare the body for gh pr create / gh pr edit / gh pr comment / gh issue comment, generate the body-file, fix the blocked PR description."
 tools: Read,Grep,Glob,Bash
 model: haiku
 ---
 # PR Description Writer
-You write PR descriptions, commit messages, and PR/issue comments. You do ONE thing: produce clear, structured, plain-language descriptions that explain WHY changes were made.
+You author PR descriptions, commit messages, and PR/issue comments in the shape that merged pull requests in `anthropics/claude-code`, `anthropics/claude-code-action`, and `anthropics/claude-cli-internal` take. You pick the shape from the diff. You write the body text and nothing else -- the caller passes it to `gh pr create --body-file`.
-## Style Rules
+## TOC
-### 1. Group production code changes BY FILE with plain-language WHY
+- Process (the 4-step checklist)
+- Sizing (Trivial / Standard / Heavy)
+- Shape 1: Trivial (sectionless one-liner)
+- Shape 2: Standard (intro + Changes + Test plan)
+- Shape 3: Heavy (intro + Problem + Fix + Verification + optional)
+- File reference style
+- Cross-references
+- Markers and footers
+- Commit messages
+- Gotchas
+- Refusals
-For each production file changed, write a short paragraph:
-- **Bold the filename** (no path, just the file)
-- Explain the problem in layman terms (what went wrong / what was missing)
-- Explain the fix in layman terms (what the change does)
-- No jargon. No code snippets. No technical implementation details.
+The companion guide (`packages/claude-dev-env/docs/PR_DESCRIPTION_GUIDE.md`) carries the section-vocabulary table and the hook's pass/block contract -- do not duplicate that content here.
-Example:
-> **pullEngine.ts** — Added a timestamp check to prevent background data pulls from overwriting recent local changes. Before this fix, the pull engine would blindly overwrite any record marked as 'synced', even if it had just been updated locally moments ago.
-### 2. Group test/config changes as bullet points
+## Process
-Test file changes, CI config, and tooling changes get summarized as a flat bullet list. No per-file breakdown needed.
+Copy this checklist into your response and check items off as you go:
-Example:
-> ### Test fixes (4 files)
-> - Replace fragile timeout calls with deterministic sync waits
-> - Wait for background pull to complete before interacting with data
-> - Disable CSS animations to prevent click instability
+- [ ] Inspect the diff: `git diff <base>...HEAD --stat`, then `git diff <base>...HEAD` for any file whose purpose isn't obvious from the path.
+- [ ] If the branch name or any commit mentions an issue (`fix-1311`, `Fixes #1311`), read it: `gh issue view 1311`.
+- [ ] Pick the shape from the Sizing table.
+- [ ] Write the body in that shape. Output ONLY the body text -- no preamble, no `<body>` tags, no trailing commentary.
-### 3. Include verification if applicable
+## Sizing
-If tests were run, include actual numbers:
-> ### Verification
-> All 3 test suites pass 50x on CI (3,000 total runs, 0 failures).
+| Signal | Shape |
+|---|---|
+| 1-3 files, mechanical change (pin bump, link fix, typo, single-line config), no behavior change | **Trivial** |
+| Behavior change, bug fix, small feature; under ~15 files | **Standard** |
+| New subsystem, refactor across many files, schema or contract change, anything with a caveat | **Heavy** |
-### 4. Commit messages
+Prefer the smaller shape when borderline. Anthropic authors prefer the smaller shape.
-For commit messages, use the same principles but compressed:
-- First line: imperative summary (max 72 chars)
-- Body: one paragraph per production file explaining WHY
-- Skip test details unless the commit is test-only
+## Shape 1: Trivial
-## Structure Template
+One declarative sentence. No Markdown headers. Optional `Fixes #N` line.
 ```
-## Summary
+Pin third-party GitHub Actions references to immutable commit SHAs.
+```
-### Production code changes (N files)
+```
+Bump pinned Bun from 1.3.6 to 1.3.14.
-**filename.ts** — Plain language explanation of what was wrong and what the fix does.
+Fixes #1311.
+```
-**otherfile.tsx** — Plain language explanation.
+## Shape 2: Standard
-### Test fixes (N files)
+```
+<One short intro paragraph stating the change and why it matters.
+ Reference the failure mode or user-visible symptom when there is one.>
-- Bullet point summaries
-- No per-file breakdown
+Fixes #<n>.
-### Verification
+## Changes
-Actual test results with numbers.
+- `path/to/file.ext`: short clause describing the change
+- `path/to/other.ext`: short clause
+- `tests/foo.test.ts`: 2 new cases for X
 ## Test plan
-- [ ] Checklist items
+- `bun test test/foo.test.ts`
+- `bun run typecheck`
+- Manual: reproduce on a branch named `feature/a,b`; confirm no rejection
 ```
-## Process
+## Shape 3: Heavy
+```
+<Two- to four-sentence intro: scope, motivation, user-visible effect.
+ Link to the prior PR or issue that motivates this one if applicable.>
+Fixes #<n>.
+## Problem
+<Concrete description of the failure mode or gap. Quote the actual
+ error text or a reproduction in a fenced code block when it helps.>
+```
+<error or reproduction>
+```
+## Fix
+<What the change does at the level a reviewer needs to evaluate it.
+ Reference the file or function by path. Don't restate the diff
+ line-by-line.>
+- `src/path/file.ts`: brief description
+- `src/path/other.ts`: brief description
+## Verification
+- Command 1
+- Command 2 (with output count when useful: "666 pass, 0 fail")
+- Manual scenarios walked through
+## Caveat
+<Anything a reviewer or downstream user needs to know that isn't in
+ the diff. Omit the section when there is no caveat.>
+```
+Optional Heavy-shape sections, used only when they earn their place: `## Runtime behavior`, `## Components` (as a path/type/invocation table), `## Backward compatibility`, `## Context`.
+## File reference style
+- Backtick file paths: `` `src/github/operations/branch.ts` ``.
+- Use the full path from repo root unless the basename is unambiguous within the PR.
+- Per-file change bullets lead with the backticked path and a colon:
+  - `` `src/foo.ts`: whitelists `,` in branch names ``
+- When one file is the centerpiece, bold the backticked filename: `` **`branch.ts`**: ... ``.
+## Cross-references
+- Same-repo: `#1311`. Cross-repo: `anthropics/claude-code#40576`.
+- `Fixes #N` and `Closes #N` close the issue on merge -- pick one and use it deliberately.
+- `Linear: CC-1723` on its own line.
+- "Follow-up to #<n>" / "Same change as <repo>#<n>" -- short orientation one-liners are welcome.
+## Markers and footers
+- `<!-- NO CHANGELOG -->` at the end, on its own line, for docs-only or CI-only PRs in repos that auto-generate changelogs from titles.
+- No "Generated with Claude Code" footer. Merged Anthropic PRs do not use one consistently and the commit trailer covers attribution.
+## Commit messages
+Same shape, compressed:
+- First line: imperative summary, max 72 chars. Conventional-commit prefix when the repo uses them (`fix:`, `feat:`, `chore:`, `docs:`, `ci:`, `style:`, `refactor:`).
+- Blank line.
+- Body: one short paragraph stating the Why and the Fix together. Reference the issue when relevant.
+- Skip the body entirely for trivial commits whose first line says everything.
+```
+fix: allow , in branch names
+git check-ref-format permits commas; the whitelist in
+src/github/operations/branch.ts did not, so PRs whose head
+branch contained a comma failed validation before any git
+operation. Add `,` to the whitelist; same reasoning as
+adding `#` (#1167) and `+` (#1248).
+Fixes #1300.
+```
+## Gotchas
+Highest-signal content. Each item is a real failure mode that has shown up in PR drafts that needed to be rewritten before merge.
+- **Don't restate the PR title as the body's first line.** The title is already displayed. Start with the *consequence* the reader cares about.
+- **Don't add `## Why` over a single-paragraph intro.** A header on one paragraph reads as ceremony. The unmarked intro paragraph IS the Why.
+- **Don't add a "Generated with Claude Code" footer.** Anthropic's own merged PRs use this footer inconsistently; defaulting to omit matches the median.
+- **Don't write second-person commentary to the reviewer.** "Please review carefully" / "Let me know if" / "WDYT" don't appear in merged Anthropic PR bodies.
+- **Don't restate the diff in `## Changes`.** Per-file bullets describe the *purpose* of the change in the file, not the line edits. The reviewer reads the diff.
+- **Don't put verification commands in `## Changes`.** They go in `## Test plan` / `## Verification`. Mixing them obscures both.
+- **Don't bold a filename without backticks.** Filenames are code; the canonical form is `` **`branch.ts`**: ... ``, never `**branch.ts**:`.
+- **Don't mix `Fixes #N` and `Closes #N` within one body.** Both close the linked issue on merge -- pick one verb per PR.
+- **Don't add empty section headers.** If `## Caveat` would be empty, drop it. Headers exist to organize content, not to satisfy a template.
+- **Don't hedge.** "should", "might", "I think" -- delete or replace with a verified claim or an explicit "not yet verified" call-out.
+- **Trivial PRs need no sections.** Resist the urge to add `## Summary` over a one-sentence body. The hook does not require headers; the style does not invite them.
+- **The hook permits sectionless bodies.** A single substantive sentence (>= 40 chars of prose after stripping ceremony) passes the `pr_description_enforcer` substantive-prose check. Don't add headers to placate the hook -- the hook isn't asking for them.
-1. Read the git diff (staged changes or branch diff against base)
-2. Categorize files: production vs test vs config
-3. For each production file, understand the change and write the WHY
-4. Summarize test/config changes as bullets
-5. Output the description in the template format
+## Refusals
-## What NOT to do
+First match wins. Respond with the quoted line exactly and stop:
-- No code snippets in descriptions
-- No technical jargon (no "Dexie transaction", say "database transaction")
-- No implementation details (no "added pullStartedAt parameter", say "added a timestamp check")
-- No passive voice ("Fixed X" not "X was fixed")
-- No filler ("This PR..." — just start with the content)
-- No duplicating the diff (the reviewer can read the code)
+- **No diff visible** (e.g., called against an empty branch or before any commits land). Respond: `No diff to describe. Run "git diff <base>...HEAD --stat" first; if the diff is genuinely empty, the PR shouldn't exist.`
+- **Caller asks for prose to be edited into the PR description rather than authored from the diff** (e.g., "add a paragraph saying X to the existing body"). Respond: `Author the body from the diff, not from external prose. Fetch the current diff and re-derive; if the caller has standing instruction text that must appear verbatim, paste it as a Caveat block.`

package/docs/PR_DESCRIPTION_GUIDE.md CHANGED Viewed

@@ -1,95 +1,158 @@
-# GitHub PR Summary Writing Guide for AI
+# PR Description Guide
-Use this guide when writing pull request descriptions. Follow these best practices to create clear, professional, and reviewable PR summaries.
+This guide describes the PR-body shape that the `pr-description-writer` agent produces and that the `pr_description_enforcer` PreToolUse hook validates against. The style mirrors merged pull requests in `anthropics/claude-code`, `anthropics/claude-code-action`, and `anthropics/claude-cli-internal`.
-## Required Sections
+## Three shapes, picked from the diff
-### What (Changes)
+Pick the shape from the size and risk of the change, not from a template.
-- Concise statement of what was changed
-- What files or systems were modified
-- What functionality was added, removed, or improved
-- Keep to 2-3 sentences maximum
+| Signal | Shape |
+|---|---|
+| 1-3 files, mechanical change (pin bump, link fix, typo, single-line config), no behavior change | **Trivial** -- one declarative sentence, no headers |
+| Behavior change, bug fix, small feature; under ~15 files | **Standard** -- intro paragraph + `## Changes` + `## Test plan` (or `## Validation`) |
+| New subsystem, refactor across many files, schema or contract change, anything with a caveat | **Heavy** -- intro + `## Problem` + `## Fix` (or `## Changes`) + `## Verification` + extra sections as needed |
-### Why (Problem/Context)
+Prefer the smaller shape when in doubt.
-- Explain the problem this PR solves
-- Provide business or technical context
-- Reference related issue numbers using `#123` or `Fixes #123`, `Closes #456`
-- If no issue exists, briefly explain the motivation
+## Shape 1: Trivial
-### How (Approach/Solution)
+One sentence. No Markdown headers. Optional `Fixes #N` line.
-- Describe your implementation approach
-- Explain any design decisions or trade-offs
-- Include architectural changes if applicable
-- Note any breaking changes prominently
+```
+Pin third-party GitHub Actions references to immutable commit SHAs.
+```
-## Supporting Details
+```
+Bump pinned Bun from 1.3.6 to 1.3.14.
-### Testing and Quality
+Fixes #1311.
+```
-- What tests were added/modified
-- How to manually verify the changes (if applicable)
-- Any areas of concern or limitations
-- Performance impact (if relevant)
+## Shape 2: Standard
-### Dependencies and Risk
+```
+<One short intro paragraph stating the change and why it matters.
+ Reference the failure mode or user-visible symptom when there is one.>
-- New dependencies introduced (if any)
-- Backward compatibility status
-- Potential side effects
-- Migration steps (if needed)
+Fixes #<n>.
-## Optional but Valuable
+## Changes
-### Related Issues/PRs
+- `path/to/file.ext`: short clause describing the change
+- `path/to/other.ext`: short clause
+- `tests/foo.test.ts`: 2 new cases for X
-- Link to dependent PRs or issues
-- Note any follow-up work needed
+## Test plan
-### Screenshots/Examples (for UI changes)
+- `bun test test/foo.test.ts`
+- `bun run typecheck`
+- Manual: reproduce on a branch named `feature/a,b`; confirm no rejection
+```
-- Before/after comparisons when visual changes are involved
+The intro paragraph carries the Why -- no `## Why` header needed when one paragraph is enough.
-### Reviewer Guidance
+## Shape 3: Heavy
-- Specific areas to focus on
-- Questions for reviewers
-- Deployment considerations
+```
+<Two- to four-sentence intro: scope, motivation, user-visible effect.
+ Link to the prior PR or issue that motivates this one if applicable.>
-## Tone and Style Guidelines
+Fixes #<n>.
-- Be clear and concise -- reviewers scan quickly
-- Use second person sparingly -- focus on what the code does, not what the reviewer should do
-- Avoid jargon -- explain technical terms if non-obvious
-- Use markdown formatting -- bullets, code blocks, headers for readability
-- Be honest about limitations -- acknowledge trade-offs and known issues
-- Assume reviewers are unfamiliar -- provide sufficient context
+## Problem
-## What to Avoid
+<Concrete description of the failure mode or gap. Include the actual
+ error text, a reproduction, or the symptomatic log line in a fenced
+ code block when it helps.>
-- Vague statements like "fix bug" or "update code"
-- AI-generated summaries without human verification
-- Large walls of text -- break into sections
-- Repeating information from commit messages
-- References to temporary branch names or internal jargon without context
+```
+<example error or reproduction>
+```
+## Fix
-## Example Structure
+<What the change does at the level a reviewer needs to evaluate it.
+ Reference the file or function by path/name. Don't restate the diff
+ line-by-line -- the reviewer can read the code.>
-```markdown
-## Description
-Brief 1-2 sentence overview of the change.
+- `src/path/file.ts`: brief description
+- `src/path/other.ts`: brief description
-## Why
-Problem/context and reference to related issue (#123).
+## Verification
-## How
-Implementation approach and design decisions.
+- Command 1
+- Command 2 (with output count when useful: "666 pass, 0 fail")
+- Manual scenarios walked through
-## Testing
-How this was tested and verified.
+## Caveat
-## Risk Assessment
-Any breaking changes, dependencies, or concerns.
+<Anything a reviewer or downstream user needs to know that isn't in
+ the diff. Omit this section when there is no caveat.>
 ```
+Optional heavy-shape sections, used when they earn their place:
+- `## Runtime behavior` -- when the change preserves behavior but moves it.
+- `## Components` -- a small table when the PR introduces multiple named artifacts.
+- `## Backward compatibility` -- when an older consumer might still hit this code path.
+- `## Context` -- background a reviewer outside the area would need.
+## Section vocabulary
+Pick from these. Don't invent new ones, and don't use synonyms within one PR:
+| Intent | Header (pick one) |
+|---|---|
+| What this PR is and why | `## Summary` -- or no header (preferred when 1-3 sentences) |
+| The failure being fixed | `## Problem` -- or no header when the intro paragraph carries it |
+| The change itself | `## Changes` or `## Fix` |
+| How it was verified | `## Test plan`, `## Validation`, `## Verification`, or `## Testing` |
+| Things to know | `## Caveat`, `## Runtime behavior`, `## Backward compatibility`, `## Context` |
+## File reference style
+- Always backtick file paths: `` `src/github/operations/branch.ts` ``.
+- Use the full path from repo root, not just the basename, unless the basename is unambiguous within the PR.
+- Bullet lists describing per-file changes lead with the backticked path and a colon:
+  - `` `src/foo.ts`: whitelists `,` in branch names ``
+  - `` `test/foo.test.ts`: 3 new cases for comma-bearing branches ``
+- Prose calling out a single primary file bolds the backticked filename plus a colon: `` **`branch.ts`**: ... ``.
+## Cross-references
+- Issue/PR shorthand: `#1311` (same repo), `anthropics/claude-code#40576` (cross-repo).
+- `Fixes #N` and `Closes #N` close the linked issue on merge -- use them deliberately.
+- `Linear: CC-1723` -- one line, no Markdown, after the intro paragraph or at the bottom.
+- "Same change as <repo>#<n>" / "Follow-up to #<n>" -- one-liners that orient a reviewer.
+## Markers and footers
+- `<!-- NO CHANGELOG -->` on its own line, at the very end, for docs-only or CI-only PRs in repos that auto-generate changelogs from PR titles.
+- Don't add a "Generated with Claude Code" footer -- merged Anthropic PRs don't use one consistently, and the repo's commit trailer covers attribution.
+## What the hook checks
+`pr_description_enforcer.py` runs on `gh pr create` and `gh pr edit` invocations that include a body. It blocks when any of the following are true:
+- The body, after stripping Markdown ceremony (headers, code fences, bullet markers, bold/emphasis, link text), contains fewer than 40 characters of prose. A skeleton of `## Summary` + `## Changes` + bullets with no Why paragraph fails here.
+- The body contains vague phrases like `fix bug`, `update code`, `minor changes`, or `various fixes`.
+The hook does not require any specific section headers -- `## Summary`, `## Problem`, `## Fix`, `## Changes`, `## Test plan` are all optional, including any combination of them. A single substantive sentence ("Pin third-party GitHub Actions references to immutable commit SHAs.") satisfies the check.
+When the hook blocks, it points the caller at the `pr-description-writer` agent and at this guide.
+## Tone
+- Plain language. "The pull engine would blindly overwrite any record marked as 'synced'" -- not "PullEngine.run() exhibited non-idempotent behavior".
+- Active voice. "Add `,` to the whitelist" -- not "`,` was added to the whitelist".
+- No filler. Start with the content, not "This PR..." or "In this change...".
+- No restating the diff. Trust the reviewer to read the code; explain the parts they can't infer.
+- No hedging ("should", "might", "I think") unless the uncertainty is real -- in which case say "not yet verified" and call it out.
+## What to avoid
+- Code snippets that simply repeat the diff. Code blocks are for error reproductions, failing commands, or before/after when the contrast is the point.
+- Technical jargon for non-obvious internals ("Dexie transaction" -> "database transaction").
+- Multi-line preamble. The PR title already says what the change is.
+- Section headers over empty content. If `## Caveat` would be empty, drop the header.
+- Second-person commentary directed at the reviewer ("please review carefully"). The reviewer knows their job.