From 958efe99770c46341816e57bd0c8affd3ca2f15c Mon Sep 17 00:00:00 2001 From: Alex Smith Date: Tue, 4 Aug 2026 07:34:46 -0400 Subject: [PATCH 1/2] docs: codify the framing, lint, and reviewer lessons from this PR Three contract additions distilled from shipping the forms post: the blog voice gains the sell-what-the-reader-keeps rule (both framing corrections on this PR were the same lesson, and the title change followed it); docs conventions gain the docs-scripts lint requirement plus the validate-via-the-open-page-DOM-not-source-regexes lesson; the AI loop section documents where the deep review output lands and how CodeRabbit's rate-limited incremental reviews resume. --- CLAUDE.md | 9 ++++++++- docs/CLAUDE.md | 7 +++++++ docs/blog/CLAUDE.md | 7 +++++++ 3 files changed, 22 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 837a4da9e..86e6fbc76 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -104,7 +104,14 @@ green and every AI review thread is resolved. an auto-applied `claude-assisted` provenance label. - **Deep review on demand:** a triage+ user can apply the opt-in `deep-review` label to any PR to run the Claude deep review on it (re-applying the label re-runs it; a - `deep-review:`-prefixed PR comment from a triage+ user pre-steers its focus). + `deep-review:`-prefixed PR comment from a triage+ user pre-steers its focus). Its output + lands as a PR review from `claude` marked ``, tied to the head + sha it started from — after later pushes, look for that review, not the current head's + checks. +- **Reviewer mechanics:** CodeRabbit reviews incrementally and rate-limits on OSS — after a + "review limit reached" skip nothing retries on its own; push a commit or have a triage+ + user comment `@coderabbitai review` once the window resets. Copilot also auto-reviews PRs + and re-reviews on push. - **State comment:** the `` PR comment is machine-managed — never reformat its first line. - **Refusals:** the loop refuses PRs that touch `.github/**` or the diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md index 39d357922..f6be7f971 100644 --- a/docs/CLAUDE.md +++ b/docs/CLAUDE.md @@ -108,3 +108,10 @@ it, so a novel non-standard `package.json` key and extra release churn weren't w `docusaurus.config.js` does not override it. That is load-bearing but easy to miss: setting `format: 'detect'` would make every `.md` page render its tags as literal text. - Markdown is prettier-formatted (`pnpm format:check` covers `md`/`mdx`). +- Scripts in `docs/scripts/` are covered by the root `pnpm lint` — run it before pushing even + a docs-only PR (#471 broke CI on exactly this). Playwright `page.evaluate` callbacks + execute in the browser, so declare `/* global document, getComputedStyle */` the way + `rasterize-cover.mjs` and bulma-ui's `capture-stories.mjs` do — and when a script already + has the page open, validate through the parsed DOM and computed styles, not regexes over + the source (quoting, `data-*` attributes, and transparent paint all fool regexes; two + review rounds proved it). diff --git a/docs/blog/CLAUDE.md b/docs/blog/CLAUDE.md index 2c81a4bcc..61eff600e 100644 --- a/docs/blog/CLAUDE.md +++ b/docs/blog/CLAUDE.md @@ -20,6 +20,13 @@ version bump) and the intro of the first State of React edition: candid, plain, accidental major bump. Never open with "We're excited to announce" (the pre-guide posts do; don't copy them). No superlatives, no hype adjectives. If a thing shipped late, say it shipped late. +- **Sell what the reader keeps, never the absence.** When the angle is something the library + deliberately omits (no form library, no date library), state the stance once, factually, + with the reasons, then let demos carry the argument: lead with what the reader keeps, name + competing libraries neutrally, and include an explicit bring-your-own path. Titles too: + "Form Library Agnostic" shipped over "Building Forms Without a Form Library" because + absence-titles read as missing features (#471). The v3 post's "no date library in your + bundle" paragraph is the model. - **Work all three appeals.** A post should persuade on ethos, pathos, and logos together. _Ethos_: write from first-hand maintainer experience, link your sources, and own the mistakes (the candor above is the credibility play). _Pathos_: name the pain a change From c3aeeb0d01e6b8e680692d9fb8e229ad5ae4393f Mon Sep 17 00:00:00 2001 From: Alex Smith Date: Tue, 4 Aug 2026 08:01:38 -0400 Subject: [PATCH 2/2] docs: correct the reviewer-mechanics claims per review Per review: the deep review posts without a commit_id, so GitHub ties it to the head at post time rather than the sha the workflow started from; the contract now says to verify findings against current code instead of asserting that association. capture-stories.mjs declares only document, so the globals guidance now says to declare what each callback actually uses. The rate-limit sentence no longer parses as CodeRabbit retrying on its own, and the unverified triage+ qualifier on the review command is dropped. --- CLAUDE.md | 15 ++++++++------- docs/CLAUDE.md | 5 +++-- 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 86e6fbc76..d8ecf72b9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -105,13 +105,14 @@ green and every AI review thread is resolved. - **Deep review on demand:** a triage+ user can apply the opt-in `deep-review` label to any PR to run the Claude deep review on it (re-applying the label re-runs it; a `deep-review:`-prefixed PR comment from a triage+ user pre-steers its focus). Its output - lands as a PR review from `claude` marked ``, tied to the head - sha it started from — after later pushes, look for that review, not the current head's - checks. -- **Reviewer mechanics:** CodeRabbit reviews incrementally and rate-limits on OSS — after a - "review limit reached" skip nothing retries on its own; push a commit or have a triage+ - user comment `@coderabbitai review` once the window resets. Copilot also auto-reviews PRs - and re-reviews on push. + lands as a PR review from `claude` marked ``; it reviewed the + code checked out when its workflow started, which a racing push may have superseded — so + look for that review comment (not the current head's checks) and verify its findings + against current code. +- **Reviewer mechanics:** CodeRabbit reviews incrementally and rate-limits on OSS. After it + posts "review limit reached" it will not retry on its own; once the window resets, push a + commit or comment `@coderabbitai review`. Copilot also auto-reviews PRs and re-reviews on + push. - **State comment:** the `` PR comment is machine-managed — never reformat its first line. - **Refusals:** the loop refuses PRs that touch `.github/**` or the diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md index f6be7f971..6ff3385f6 100644 --- a/docs/CLAUDE.md +++ b/docs/CLAUDE.md @@ -110,8 +110,9 @@ it, so a novel non-standard `package.json` key and extra release churn weren't w - Markdown is prettier-formatted (`pnpm format:check` covers `md`/`mdx`). - Scripts in `docs/scripts/` are covered by the root `pnpm lint` — run it before pushing even a docs-only PR (#471 broke CI on exactly this). Playwright `page.evaluate` callbacks - execute in the browser, so declare `/* global document, getComputedStyle */` the way - `rasterize-cover.mjs` and bulma-ui's `capture-stories.mjs` do — and when a script already + execute in the browser, so declare the browser globals each callback actually uses + (`/* global document */` in bulma-ui's `capture-stories.mjs`; + `/* global document, getComputedStyle */` in `rasterize-cover.mjs`) — and when a script already has the page open, validate through the parsed DOM and computed styles, not regexes over the source (quoting, `data-*` attributes, and transparent paint all fool regexes; two review rounds proved it).