CodeRabbit Conventions

Settled — do not re-propose

• Sizing a window with gh pr view --json changedFiles. It counts the cumulative diff against the base branch rather than what moved since the last completed review, so on this repo's standing develop→main PR it reads a multiple of the real window and manufactures an over-cap emergency out of a healthy push. It is the fastest thing to reach for and wrong every time a PR has been reviewed more than once, which is every time. Read the frontier (references/measuring-the-window.md).
• Adding develop to reviews.auto_review.base_branches so develop-base PRs review themselves. It turns every intermediate PR into a spent slot; a develop-base PR is triggered by hand with @coderabbitai review ("What Triggers a Review").
• Excluding files to bring an over-budget window under the cap. Exclusion hides the work from the only review it will ever get. Cut the tail to a queue branch and re-push a sub-cap window instead (references/exclusions.md, references/release-pr-cutting.md).
• Holding a finished chunk until format/typecheck/lint/tests come back. Checks are minutes and a slot is an hour, so that spends the scarce resource to protect the cheap one — and a failure found afterwards is one more commit in the next window (references/pipelining.md).
• One roadmap item per PR. A slot costs an hour whether it reads 12 files or 90, so an under-filled window is the most expensive kind ("PR File Budget").
• Grepping the review body for the word "nitpick" to collect them. The buckets are not a fixed set — duplicates, refactor suggestions and an additional-comments block appear once a review carries many — so a grep silently drops whichever bucket it did not name (references/review-feedback.md).

What Triggers a Review

CodeRabbit auto-reviews only PRs targeting the default branch (main). Develop-base PRs are skipped ("Auto reviews are disabled on base/target branches other than the default branch") and are triggered by commenting @coderabbitai review.

Never add reviews.auto_review.base_branches. Manual triggering there is deliberate, not a gap: it keeps control of when a review starts — which is what makes the never-push-into-a-running-review rule below workable — and stops every intermediate push spending a rate-limit slot. If a PR was not reviewed, comment @coderabbitai review; do not change the config. The setting reads like an obvious fix and has been "helpfully" added before.

.coderabbit.yaml is read from the PR's base branch, so a config change only takes effect once it is on that branch — references/config-editing.md.

Opening a PR Spends a Review Slot — references/opening-a-pr.md

Creating a PR against the default branch, and every push to one, starts a review — so the PR is asked for every time, and the moment after gh pr create is already an in-flight review. What has to be settled before the ask, and what an author's own correction costs right after opening, is that page.

Never Push Into an In-Flight Review

Pushing while a review runs cancels it and retriggers a fresh one, costing a slot and losing the in-progress findings. CodeRabbit is incremental — it does not re-review commits it has already reviewed — so a cancelled review's comments do not come back on the next run. They are gone.

gh pr checks --json name,state,bucket,description --jq '.[] | select(.name=="CodeRabbit")'
# {"bucket":"pass","description":"Review rate limited","name":"CodeRabbit","state":"SUCCESS"}

Read bucket first, then description. bucket is gh's normalization across both representations a check can take, so pending means a live review whatever CodeRabbit reports underneath — it posts a commit status (pending/success/failure/error), while Actions entries on the same PR are check runs reporting IN_PROGRESS/QUEUED. Keying on the state string alone means a representation change reads as terminal.

bucket / description	meaning	push?
pending (any description)	live review, a push cancels it	wait
pass / Review completed	finished	push
pass / Review rate limited	never started, nothing running	push
pass / skip comment says Too many files	never started	push, but fix the count first
fail, missing row, or anything unrecognised	unknown	wait, then look

The last row is the default, not an edge case: being wrong about a running review costs its findings and a slot, being wrong about a finished one costs a minute.

Symptoms that a push landed mid-review: a > [!CAUTION] Failed to replace (edit) comment / putComment timed out comment from the bot, or a review returning far fewer comments than the diff warrants.

The Four Gates

They are not interchangeable — the first is about leaving findings unanswered, the second about cancelling a review, the third about accumulating an unreviewed window, the fourth about overflowing the cap.

flowchart TD
  C[Commit locally] --> D{Any unresolved findings from a completed review}
  D -->|yes| DR[Drain them first - they lead the next window]
  DR --> M[Measure backlog from the last reviewed sha]
  D -->|no| M
  M --> R{Is a review running}
  R -->|yes| W1[Wait - a push cancels it and loses its findings]
  R -->|no| P{Was the previous window reviewed}
  P -->|no| W2[Wait - unreviewed windows accumulate into one]
  P -->|yes| B{Is the backlog under the cap}
  B -->|no| H[Hold the overflow locally and push a smaller window]
  B -->|yes| PU[Push]
  PU --> RV[Review runs against the new range]
  RV --> F[Fix findings then reply with the pushed sha]
  F --> C

Drain the open findings before composing a window — they are its first commits, not its last. A completed review's findings are the only work with an expiry date: threads go stale as the code under them moves, a finding answered three windows later is answered against code the reviewer never saw, and the reviewer re-raises what looks unaddressed. Fresh work has no such clock, so it always yields. This gates what the window contains, not merely its order: a window that would exceed the cap drops queued work to keep the fixes in. Count what is open before deciding it is drained (references/review-feedback.md — an empty result is usually a wrong filter, not a clean PR).

The check answers "is one running", never "has the last push been reviewed". Review completed is the status of whichever review ran most recently, which may have covered a range two pushes back — the check names no range at all, so reading it as clearance for the current head is a category error. Reading the last reviewed sha, sizing the window against it, and why a rate-limited status is not proof the frontier stalled: references/measuring-the-window.md.

This says when a push is safe, never when it is authorised. The standing rule overrides everything here: commit the coherent change and never push develop unless the user asks — rate-limited, recovery and force-pushes alike. Pushing queue is not that: it spends nothing and is how work reaches the collector, which holds the standing authorisation for develop and clears these gates on every run (references/pipelining.md). Given the ask, Review rate limited is not a wait state: nothing is running, so holding the branch stalls the working tree for an hour to protect a review that does not exist. Under a standing ask ("keep pushing while it's parked"), treat the review as an async thread and keep pushing rather than waiting for one to be asked for each time. The ask supplies authorisation, never an exemption from the gates — every push still clears all four, the in-flight gate included, so a standing ask never licenses pushing into a running review. It applies per push, not per work session: the second push re-reads the gates from scratch, and if the first push's review is still running it waits, however recently permission was given.

PR File Budget

The cap is 100 files per review — the Open Source tier's limit is popularity-scaled and can move, so treat it as current-best-known; the bot's skip comment states the current one. Push the largest commit prefix under the cap — ~90 is where one usually lands, never a reason to hold a 99-file prefix — counting the union of committed and working-tree changes, and measuring per cycle rather than per PR (references/measuring-the-window.md). How a sitting is cut into that prefix so the pushed head is green on its own: references/window-composition.md.

The budget is a target to fill, not only a cap. A slot costs an hour whether it reads 12 files or 90, so an under-filled window is the most expensive kind; roadmap items are batched until the estimate approaches ~90, grouped by what they touch (references/window-composition.md).

Pipelining — references/pipelining.md

There are no per-chunk feature branches and the session never pushes develop: it works on queue and pushes it after every commit, and the review collector (pnpm ai:coderabbit:collect, run by the ReviewCollector workflow on every queue push and every CodeRabbit review) clears the four gates from the remote, drains open findings onto review-fixes, and fast-forwards develop by the largest green window under the cap. The single long-lived develop → main PR auto-reviews every such push. What the session pushes, what it never touches, and how it catches up after the collector moves develop is that page.

Reading and Answering Findings

"Fix the CodeRabbit comments" means every finding the run produced, at every severity and in every place the run put one. Nobody has to list the categories, and a request naming one of them ("the review comments") is not a request scoped to that one. A finding is skipped only when it is genuinely invalid, and then it is answered like any other: a reply saying why. Severity and delivery channel are different axes — a minor arrives as an inline thread as readily as a major — and it is the channel, never the severity, that decides whether a fetch finds it.

• Reply to every finding, including rejected ones — the verdict in the first line (Agreed, fixed in <sha> / Not a real issue, no change) and the evidence; a silent skip is indistinguishable from an oversight.
• Push the fix commits first, then reply — a reply citing a sha the remote does not have is one CodeRabbit cannot resolve.
• Verify before accepting — CodeRabbit reasons from names and prior "learnings" and asserts semantics the code does not have; check the implementation, and grep for the repo's convention before taking a suggested diff.
• Where each kind of finding lives (nitpicks and outside-diff-range findings in the review body, the Merge Risk verdict in the walkthrough), reconciling against the stated counts, answering an invalid class in .coderabbit.yaml, and why an enforcer over the repo's files does not constrain a pure function's parameter: references/answering-findings.md.

Deep Dives

• references/opening-a-pr.md — before gh pr create against the default branch, or in the minutes after one ran.
• references/review-feedback.md — when fetching a PR's feedback, counting what is still open, probing the checkpoint, or replying to a comment.
• references/measuring-the-window.md — before a push: reading the last reviewed sha, counting the backlog against it, and what a rate-limited status does and does not prove.
• references/pipelining.md — when planning the push cadence, or deciding where a window boundary falls.
• references/window-composition.md — when a push would exceed the cap, work authored last has to be reviewed first, or roadmap items are being batched into one window.
• references/answering-findings.md — when a completed review's findings are being collected, fixed and replied to.
• references/config-editing.md — when changing .coderabbit.yaml.
• references/release-pr-cutting.md — when a PR has grown past the file limit and its review is skipped outright.
• references/exclusions.md — when deciding whether a file may be excluded, generating the list, or removing the exclusions.