Windsurf Code Review: Build a Current-Head Gate

How should Windsurf code review fit into a merge gate?

Use Windsurf Quick Review as a local preflight, use Windsurf or Devin Review to produce pull-request findings, and use repository-owned CI to decide whether the current head may merge. Every commit or autofix starts a new review epoch. A clean result for an older revision is evidence, not approval for the latest code.

That separation matters because Windsurf now exposes two useful review loops. Quick Review asks a separate agent to inspect local changes before commit. The pull-request workflow publishes durable feedback on GitHub and can connect findings to agent-generated fixes. Those loops shorten feedback time, but they answer different questions from a required check.

A repository gate asks a narrower question: did the exact commit at the pull request head pass the tests, review policy, and unresolved-finding rules that the repository requires? The generalmerge-safe AI code review workflowexplains that GitHub contract. This guide applies it to Windsurf's local review, pull-request review, and autofix transitions.

If Devin Review is the primary pull-request surface rather than a Windsurf follow-up, use the Devin review authority contract to inventory read, report, mutation, and merge permissions before enabling write actions.

Windsurf code review has two different surfaces

The phrase “Windsurf code review” can hide two separate products. Conflating them creates stale evidence and unclear ownership. Name the surface in your process so reviewers know what code was inspected and where the result lives.

Windsurf's currentQuick Review documentationdescribes an agentic review of local changes by a secondary agent. It currently offers the lightweight SWE-check model without a usage charge across tiers and token-priced frontier models for deeper passes. Treat those details as dated to August 7, 2026; model names, quotas, and billing are product settings, not stable repository contracts.

The currentWindsurf PR Reviews documentationlabels the feature beta for Teams and Enterprise customers using GitHub Cloud. An organization administrator connects the GitHub bot, chooses repositories, and configures review guidance. Eligible pull requests can be reviewed when marked ready or manually triggered, with feedback published as GitHub review comments.

These are strong author and reviewer experiences. They are not interchangeable with a repository verdict. GitHub's ownprotected-branch documentationsays required status checks must pass before a protected branch can merge. That check layer is where a repository expresses pass, failure, and freshness policy.

The review-epoch contract prevents stale Windsurf verdicts

A review epoch is the period in which one exact code state remains unchanged. The epoch begins when a local diff or pull-request head is selected for review. It ends as soon as a person or agent changes that code. Comments can remain useful across epochs; a pass verdict cannot.

This is the information that most editor and pull-request guides omit. They explain how to request a review and fix a comment, but not how the fix invalidates the state the reviewer saw. Windsurf makes the transition especially important because Devin Review can connect a finding to Autofix. The officialDevin Review launch postsays that, when Autofix is enabled, Devin can generate a fix and apply it to the pull-request branch. That is a new head and therefore a new epoch.

1. Define the review contract before asking Windsurf

A useful review starts with a falsifiable change contract. State what behavior is supposed to change, which interfaces may move, which invariants must remain true, what tests demonstrate success, and what is explicitly outside scope. “Review this PR” leaves the model to invent the standard after reading the implementation.

Keep repository facts in versioned files. Windsurf's current rules documentation says Devin Desktop discovers workspace rules and AGENTS.md, with a rootAGENTS.md applied broadly and nested files scoped by location. Use those files for durable engineering constraints. Use the PR description for the change contract. Use the Windsurf team setting for PR Guidelines to express concise review priorities that apply to the connected repositories.

Do not copy the same large instruction block into every surface. Repository rules should describe stable constraints. PR Guidelines should tell the reviewer what evidence and severity standard to use. The pull-request body should explain this change. Duplication makes drift hard to detect and can leave the author and reviewer operating under different contracts.

Review contract

Intent: Reject cross-tenant access before returning a project.
Affected boundary: GET /projects/:id authorization.
Must remain true: Owners and invited members retain access.
Evidence: focused authorization tests plus the full API suite.
Non-goals: no role-model or database-schema changes.

Done means another maintainer can tell what would falsify the change without reading the implementation first.

2. Run Windsurf Quick Review as a local preflight

Run Quick Review after the intended local change is complete but before you treat it as review-ready. The separate-agent design is useful because the reviewer does not share the exact conversational path that produced the patch. It can challenge an assumption the authoring agent carried forward.

Keep the local result provisional. A working tree can contain unstaged files, ignored generated output, or environment-specific state that will not exist in the pull request. Conversely, the pushed commit can include changes that the selected local diff did not cover. Record consequential findings, run focused tests, and inspect the staged diff before commit.

1. Freeze the intended local diff long enough to review one state.
2. Run Quick Review with the model appropriate to the change risk and budget.
3. Require file, line, causal path, and consequence for any proposed blocker.
4. Fix, reject with evidence, or defer each consequential finding.
5. Run the focused tests and inspect git diff --cached before commit.

If a fix changes the diff materially, the original Quick Review pass no longer covers the whole local state. Rerun it or document why the change is fully covered by deterministic tests. The goal is not to maximize review calls. The goal is to avoid describing unreviewed code as reviewed.

3. Run Windsurf PR Review on a named head commit

Push the commit, open the pull request, and record its head SHA before requesting review. Marking the pull request ready or using the current documented manual trigger asks Windsurf to review a durable GitHub state. Keep the resulting comments attached to that state even if later commits make their line anchors outdated.

The reviewer should receive enough context to evaluate the contract, but its output remains untrusted. A confident comment can still misunderstand a platform contract, miss an existing test, or cite a line that is not on the changed path. Use thesignal-first review comment contractto separate a concrete defect from a question, ambiguity, or optional suggestion.

Store the head SHA beside the review result. If the Windsurf surface does not expose a machine-readable reviewed SHA for your workflow, capture the PR head immediately before and after the review completes. If it changes during the run, request another review rather than guessing which revision the comments describe.

review_epoch:
  head_sha: "<40-character PR head>"
  reviewer: "windsurf-pr-review"
  requested_at: "<timestamp>"
  completed_at: "<timestamp>"
  state: "findings_recorded"

4. Convert Windsurf findings into explicit obligations

A review comment becomes a merge obligation only after it clears an evidence gate. The comment should name a checked claim, show the relevant code, explain the causal path to a real consequence, and state what evidence would close it. Severity and confidence alone are not evidence.

Keep the finding identity stable across reruns. Wording and line anchors may move, but the underlying obligation should not disappear because the next model expresses it differently. Structured dispositions also give repair agents a bounded work list instead of forcing them to scrape the PR conversation.

5. Invalidate the old verdict after Autofix or any push

When Devin Autofix, Windsurf, a human, or another agent pushes a commit, end the old review epoch immediately. The prior comments remain useful history. Any “clean” or “resolved” state must be recomputed against the new head.

This is where automated repair loops often become unsafe. The first reviewer finds a real problem. The repair agent changes the branch. The conversation now looks resolved, so the workflow carries the old approval forward without reviewing the fix. The new code can introduce a regression, only partially address the causal path, or invalidate another test assumption.

1. Capture the new head SHA after the fix lands.
2. Run the focused regression that demonstrates the finding is closed.
3. Run required repository checks on the new head.
4. Rerun the review or perform a bounded delta review with explicit carry-forward rules.
5. Close the finding only when evidence applies to the new head.

A delta review can be efficient when it carries unresolved findings forward and inspects every changed replacement block. It becomes dangerous when “no new comment” is interpreted as “all old obligations are fixed.” Silence is not a state transition.

6. Publish a repository-owned current-head gate

Keep the final pass-or-fail policy in the repository. A GitHub Actions workflow can run tests, validate the exact pull-request context, publish a stable check name, and emit a structured result that another agent can consume. Branch protection then requires that check instead of inferring merge readiness from comment tone.

ReviewGate is one open-source implementation of that layer. It runs in the user's CI environment with a bring-your-own OpenRouter key, publishes one canonical summary with a visible 0-5 score, and emits structured JSON. It is review-only: it does not apply fixes or make the human merge decision.

name: ReviewGate

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

jobs:
  review:
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    permissions:
      actions: read
      attestations: read
      contents: read
      pull-requests: write
      issues: write
      checks: write
      statuses: read
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
          persist-credentials: false
      - uses: LVTD-LLC/reviewgate@v0
        with:
          openrouter_api_key: ${{ secrets.OPENROUTER_API_KEY }}
          min_severity: P4

Copy the maintained workflow from theReviewGate GitHub Actions guide rather than treating this excerpt as a permanent version pin. Then configure review angles and severity through therepository configuration reference. Keep the fork guard and least-privilege permissions; do not move secret-backed review of untrusted code to pull_request_target.

The gate should distinguish code verdicts from reviewer failures. “Needs changes” means grounded obligations remain. “Review error” means the reviewer was unavailable or produced an invalid artifact. Treating an unavailable reviewer as a clean pass turns an infrastructure failure into false confidence.

7. Verify the pull request current head before merge

Read the pull request head SHA, the CI/check-run SHA, and the review artifact's reviewed SHA as separate fields. They must converge on the same commit. A green workflow from an earlier head and a newly pushed branch are not a green current pull request.

GitHub supports strict required checks that also require the branch to be current with the base branch. For busy repositories, a merge queue can test the proposed change with the latest target branch and queued work. Choose the branch policy that matches your integration risk, but preserve the same invariant: the code being merged must be the code covered by the required results.

1. Read the live pull request head SHA.
2. Confirm every required check completed for that head.
3. Confirm the structured review result names that same head.
4. Confirm no admitted blocker remains still_open or needs_human.
5. Review human comments and conversation-resolution requirements.
6. Let the authorized human make the merge decision.

ReviewGate'sagent workflow contract exposes the reviewed SHA, status, score, and canonical finding state so external agents can stop on a stale or inconclusive result instead of parsing prose. The fixed passing target is 5/5, but a fresh score is still one input to the maintainer's decision.

A worked review-epoch transition

Consider a pull request that adds a tenant check to a project endpoint. This is an illustrative state transition, not a claim about a real Windsurf review.

1. The authoring agent changes the authorization function. Quick Review inspects the local diff. Focused tests pass, and the author commits head A.
2. Windsurf PR Review inspects head A and reports that invited members are rejected with owners. The maintainer admits the finding because it cites the changed predicate, the membership contract, and a missing regression test.
3. Devin Autofix updates the predicate and adds a test, producing head B. The finding from head A remains the reason for the change, but the old review verdict is stale.
4. Required CI and the repository review gate run on head B. The focused test proves the invited-member path, the full suite passes, and the structured result names head B with no open blockers.
5. A maintainer checks the intended authorization contract and merges headB. The history preserves the original finding and the evidence that closed it.

The useful property is not which agent found or fixed the issue. The workflow can explain the state change from finding to evidence to current-head verdict. That makes the process auditable when the editor, PR reviewer, and repair agent all come from the same product family.

Common Windsurf code review failure modes

Treating local feedback as pull-request evidence

Quick Review sees a local state. The pull request contains commits. Compare the staged and pushed diff, then run the durable review on GitHub. Do not attach a local “clean” label to code that changed before push.

Letting comments become the state database

Review threads are good for discussion and poor for automation. Findings move, comments become outdated, and resolution can mean agreement rather than a verified fix. Keep one canonical machine state with stable finding identities and explicit dispositions.

Carrying approval through an Autofix

Any branch update ends the old review epoch. Rerun the focused test, required CI, and current-head review. The convenience of agent-generated repair increases the need for freshness checks because mutation happens inside the review workflow.

Using one vague instruction set everywhere

Put stable repository constraints in versioned rules, change intent in the PR body, and finding-admission policy in reviewer guidance. Each surface has a job. One large prompt copied between them will drift and consume context without clarifying who owns the contract.

Making “the bot ran” the required check

A completed review is not necessarily a passing review. Define which finding classes can block, what reviewer failure means, how stale results are rejected, and which exact status check branch protection requires. Measure the workflow with theAI code review benchmark scorecardbefore making it mandatory across repositories.

Questions about Windsurf code review

Add an exact-head gate after Windsurf review

ReviewGate is free and open source. It runs inside GitHub Actions, uses your OpenRouter key, publishes one score-centered summary, and gives humans or external agents a structured current-head result. Windsurf can remain the authoring and review workspace; ReviewGate supplies the repository-owned verdict boundary.