Repository navigation
docs: codify the framing, lint, and reviewer lessons from #471 - #473
Conversation
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.
|
Warning Review limit reached
Next review available in: 34 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
WalkthroughThe PR updates AI development, documentation validation, and blog-writing guidance in three Markdown instruction files. ChangesAI development documentation
Estimated code review effort: 1 (Trivial) | ~3 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
Codifies documentation and reviewer lessons learned from PR #471.
Changes:
- Adds blog framing guidance.
- Documents docs-script linting and browser validation.
- Clarifies AI review mechanics.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
CLAUDE.md |
Documents deep-review and reviewer behavior. |
docs/CLAUDE.md |
Adds docs-script conventions. |
docs/blog/CLAUDE.md |
Adds reader-focused framing guidance. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| lands as a PR review from `claude` marked `<!-- claude-deep-review -->`, tied to the head | ||
| sha it started from — after later pushes, look for that review, not the current head's | ||
| checks. |
| 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 |
Preview DeploymentPreview URL: https://7a2fedc7.bestax.pages.dev |
allxsmith
added
documentation
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CLAUDE.md`:
- Around line 111-114: Update the “Reviewer mechanics” guidance in CLAUDE.md to
state clearly that CodeRabbit will not retry while the OSS rate-limit window is
active, then specify the manual recovery steps: push a commit or, after the
window resets, have a triage+ user comment `@coderabbitai` review. Preserve the
existing Copilot review guidance.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: c70050c9-9361-4dfe-b25b-a541a3df50b3
📒 Files selected for processing (3)
CLAUDE.mddocs/CLAUDE.mddocs/blog/CLAUDE.md
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
Deep review — 0 blocking · 0 advisory
| # | Severity | Area | Finding | Location |
|---|---|---|---|---|
| — | — | — | No blocking defects found. | — |
Overall: This is a documentation-only PR that distills three contract lessons from #471 into CLAUDE.md, docs/CLAUDE.md, and docs/blog/CLAUDE.md. There is no runtime surface, so the review reduced to verifying the factual claims — and every empirically checkable one holds: root pnpm lint really is eslint scripts docs/scripts (so docs/scripts/ is covered on docs-only PRs), both rasterize-cover.mjs and capture-stories.mjs carry the cited /* global … */ page.evaluate declarations, the shipped title is indeed Form Library Agnostic, and the v3 post's "no date library" paragraph exists. The deep-review-output description also matches the actual mechanics (a claude review marked <!-- claude-deep-review -->). The riskiest lines are the unverifiable operational claims about CodeRabbit rate-limit/resume and Copilot re-review behavior — plausible and internally consistent, but a human should sanity-check them against current reviewer behavior.
Residual risk:
- Stale-fact drift — the value of these files is accuracy, and they're read by CodeRabbit and the
@claudeaction. Refuted for everything checkable in-repo (lint scope, global decls, blog title/paragraph). The only un-refutable items are external reviewer behaviors (CodeRabbit "review limit reached" resume, Copilot auto-review), which can't be verified from the diff. - Scope/loop safety — the PR touches only
CLAUDE.mdfiles, none of.github/**or the jest/commitlint/release/pnpm-workspace configs, so it stays inside the fix loop's allowed edit surface. No concern.
🏄 Pure docs cleanup, brah — no code to wipe out on, just three CLAUDE.md files getting the wisdom of #471 carved into the reef. Paddled out and checked every claim against the actual repo and they all held. Ship it, it's a clean glassy set.
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.
Preview DeploymentPreview URL: https://7986c49f.bestax.pages.dev |
|
🎉 This PR is included in version 4.0.1 🎉 The release is available on: Your semantic-release bot 📦🚀 |
|
🎉 This PR is included in version 5.8.1 🎉 The release is available on: Your semantic-release bot 📦🚀 |
|
🎉 This PR is included in version 1.0.0 🎉 The release is available on: Your semantic-release bot 📦🚀 |
|
🎉 This PR is included in version 2.0.1 🎉 The release is available on: Your semantic-release bot 📦🚀 |
Follow-up to #471 (merged before this landed on its branch). Three small contract additions distilled from shipping the Form Library Agnostic post, so the next agent gets there faster:
docs/blog/CLAUDE.md(voice): sell what the reader keeps, never the absence — stance stated once with reasons, neutral naming, an explicit bring-your-own path, and absence-free titles. Both framing corrections on docs: add "Form Library Agnostic" post and cover rasterize script #471 were this same lesson.docs/CLAUDE.md(conventions):docs/scripts/is covered by rootpnpm linteven on docs-only PRs (docs: add "Form Library Agnostic" post and cover rasterize script #471 broke CI on exactly this); Playwrightpage.evaluatecallbacks need/* global … */declarations; and a script that already has the page open should validate via the parsed DOM and computed styles, not source regexes.CLAUDE.md(AI development loop): where the deep review output lands (claudePR review,<!-- claude-deep-review -->, tied to its starting sha) and how CodeRabbit's rate-limited incremental reviews resume (push, or triage+@coderabbitai review).Deliberately excluded as issue-specific: cover-art technique, the hero pipeline and syndication flow (already codified in-PR on #471), and anything the
rasterize-cover.mjscomments now carry.skills/CLAUDE.mdneeds no rule change; thebestax-formSignupForm bug found during #471 gets its ownfix(create-bestax)PR.Summary by CodeRabbit