agentleFS
kratoczkratocz/skills/skills/code-review/SKILL.md

code-review

Skill1 starsChanged 50 days agoMITView on GitHub

Run a structured code review on a PR (or another target). Picks a CR title, starts timesheet logging, produces findings labelled C1/M1/m1/n1 with line references and fix snippets in `docs.local/code-reviews/`, runs verification passes, then posts inline + summary comments on GitHub. Use whenever the user asks you to review a PR, says "udělej CR", asks for a code review on a branch or diff, or otherwise wants structured review feedback.

194 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use close-spec, design-with-images and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • dzhngSkill

    close-spec

    When a spec under specs/<feature>/ is done shipping (a write-spec build, or any planned task that produced a spec), archive it to specs/done/ and rewrite it from a build-plan into a durable rationale — the why, the principles, the invariants — pointing back to the real code for the how. Use when implementation has landed and the plan no longer matches what shipped, or the user says a feature/spec is finished. Pairs with [write-spec](../write-spec/SKILL.md) (the plan this closes) and [review](../review/SKILL.md) (run before closing).

    Also in 5 projects that use this

  • dzhngSkill

    design-with-images

    Explore UI and visual design with image generation, then iterate the real implementation against the user-selected concept. Use when brainstorming visual directions, offering mockup variants, or implementing an approved generated design; do not stop at the mockups or the first code approximation.

    Also in 5 projects that use this

  • PydanticSkill

    add-new-model

    Add support for a newly-released language or image generation model in pydantic-ai (e.g. openai:gpt-5.6, anthropic:claude-sonnet-5, openai:gpt-image-2). Use when a provider ships a new model id and you need to wire literals, profile flags, adapters, and tests to recognize it. Handles SDK-lag, gateway list conventions, capability probing, and direct image-model geometry.

    Also in 10 projects that use this

  • Microsoft AzureSkill

    azsdk-common-apiview-feedback-resolution

    Analyze and resolve APIView review feedback on Azure SDK PRs. **UTILITY SKILL**. USE FOR: APIView comments, API review feedback, SDK API surface changes. DO NOT USE FOR: general code review, non-APIView feedback. INVOKES: azure-sdk-mcp:azsdk_apiview_get_comments, azure-sdk-mcp:azsdk_customized_code_update, azure-sdk-mcp:azsdk_typespec_delegate_apiview_feedback, azure-sdk-mcp:azsdk_run_typespec_validation, azure-sdk-mcp:azsdk_package_generate_code.

    Also in 6 projects that use this

  • Microsoft AzureSkill

    azsdk-common-generate-sdk-locally

    Generate and finalize Azure SDKs locally from TypeSpec, including build, checks, tests, changelog, metadata, and version updates by default. WHEN: "generate SDK locally", "build SDK", "run SDK tests", "run CI checks", "validate package", "run checks", "update changelog", "fix SDK build errors", "resolve SDK generation errors", "customize TypeSpec", "rename SDK client", "rename SDK model", "hide operation from SDK", "fix analyzer errors", "resolve customization drift", "create subclient", "update metadata", "update version". INVOKES: azsdk_verify_setup, azsdk_package_generate_code, azsdk_package_build_code, azsdk_package_run_check, azsdk_package_run_tests, azsdk_customized_code_update, azsdk_package_update_changelog_content, azsdk_package_update_metadata, azsdk_package_update_version.

    Also in 6 projects that use this

  • ww-w-aiSkill

    bkend-auth

    bkend.ai authentication guide. Signup, login, JWT tokens, sessions, role-based access control, and password management with bkend.ai BaaS. Triggers: bkend auth, bkend login, bkend signup, JWT, session, RBAC, password, bkend 인증, 로그인, 회원가입, bkend認証, ログイン, 新規登録, bkend认证, 登录, 注册, autenticacion bkend, authentification bkend, bkend-Auth Do NOT use for: data operations (use $bkend-data), file storage (use $bkend-storage).

    Also in 4 projects that use this

  • +3 more from dzhng
  • +3 more from Azure

The file

We split this skill into the rules it gives an agent

6 rules. 0 are common, 3 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 184 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When invoked, follow this procedure in order:

    line 11
  2. Very specific:

    If a single clear candidate emerges, mention it inline (e.g.

    line 18
  3. Distinctive:

    If ambiguous or no match, ask the user: a specific PR?

    line 19
  4. Distinctive:

    No prior CR → proceed.

    line 28
  5. Very specific:

    Write the findings to a file in docs.local/code-reviews/ at the project root.

    line 45
  6. Very specific:

    If docs.local/ doesn't exist, ask the user whether to create it (with the code-reviews/ subdirectory) and add docs.local/ to the project …

    line 50

“Common” is measured: kept by at least 6 in 10 of the 184 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Code review workflow

This skill executes a code review following the user's code-review conventions. If the project or global instructions file (AGENTS.md / CLAUDE.md) has a ## Code review section (severity codes, focus areas, comment language, review process), read it first; this skill is the procedure to follow.

When invoked, follow this procedure in order:

  1. Identify the target.
    • Try to auto-detect first. Match the current working directory's basename and git branch --show-current against these patterns:
      • cr-pr-<N> → target is PR #N in the repo's origin.
      • cr-<slug> → target is the branch <slug> (or <slug> as a short identifier).
      • Further fallback: gh pr view --json number,headRefName from the current checkout may identify a PR whose head is the current branch.
    • If a single clear candidate emerges, mention it inline (e.g. Detected target: PR #27 — proceeding) and move on without asking.
    • If ambiguous or no match, ask the user: a specific PR? A branch? Something else?
    • A batch target ("review every open PR by X", "all three of these") is one invocation, not N runs of this skill. Resolve the list first (gh pr list --author <handle> --state open) and name it back to the user before starting, because the set is what they will check your output against. Then: one timesheet entry naming every PR in it; one findings file per PR, since each gets its own GitHub review and its own round numbering, and they will be at different rounds — a PR reviewed before is a round N+1 with a Status of prior findings section while its neighbour is a round 1; one summary to the user covering all of them, with a per-PR verdict line; and the freshness re-check (step 12) run across the whole set immediately before posting, not per PR as you finish it. Posting the first verdict while the last PR is still unread invites the author to push to a PR you already reviewed.
    • A batch that runs code needs its resources planned, and its passes chained. Check free disk before launching agents that each copy the app and build a virtualenv: at 0.3–1 GB per agent, nineteen of them once filled a nearly full disk and took the container VM down, with unrelated containers on it. Give each agent its own database container and its own cache database index (never one another local process uses). Run the per-PR reviewers on the strongest available model tier (e.g. Claude Opus, OpenAI Astra) and the drafters and implementers on the mid tier (e.g. Claude Sonnet, OpenAI Terra). Feed each contract-breaker and refuter result back to the agent that wrote the findings file — continue it, so it amends its own file with full context — rather than to a fresh agent; the drafter of the posted text runs only after both. Keep the batch's working directory — gathered inputs, extracted trees, briefs, drafted payloads, posting scripts — under the review worktree's ignored docs.local/ rather than in the session scratchpad: a scratchpad can be withdrawn mid-session, and on 2026-10-09 one vanished between the review phase and the posting phase, so every per-PR input had to be gathered again before anything could be posted. When the batch has been posted, remove its database containers: on 2026-10-12 one was still running five hours after the batch ended, on a disk with under 4 GB free. Runtime evidence that needs a container image the agents would have to pull (an object store, a mail server, a database flavour the batch does not already run) may be refused when an agent asks for it: on 2026-10-22 the harness classifier blocked a reviewer that had been sent to pull and run a third-party image. Do not route around it — write the script yourself (container bound to 127.0.0.1, data on tmpfs, removed at the end) and hand it to the user to run with ! bash <script>, then forward the log to the agent that needs it. Brief every agent that writes a deliverable to put the full content in its final reply when its file write is refused: the same night one reviewer's write was rejected, and its findings existed only in its hand-back.
    • The orchestrator routes what it only passes on; it does not read it (kodex rule 17). End every agent's brief with what its final reply carries — the verdict, the counts by tier and anything that needs the user's decision — while the findings themselves stay in the agent's file. Hand a refuter's or contract-breaker's result back to the reviewer as the path of its file, not as a retelling. Start a new batch by copying the previous batch's briefs and scripts and adapting them with a substitution pass (paths, PR numbers, heads), not by reading them in. If the harness reports language-server diagnostics for every file an agent writes, switch that integration off for the review workspace: the agents' scratch tests otherwise flood the orchestrator with import errors. In Claude Code that is "enabledPlugins": {"<lsp-plugin>": false} in the review worktree's .claude/settings.local.json; it takes effect only in the next session started there, and a worktree created later copies the main checkout's file rather than this one, so the switch does not follow the batch to a new worktree. Check it at the start of each review session by writing one throwaway file with a bad import into an ignored directory: on 2026-10-26 a review session found the diagnostics still arriving, because the switch had been set in the previous batch's worktree only. Seen 2026-10-23: in an eight-PR batch the orchestrator's context reached ~455k tokens, of which ~55k were agents' final reports, ~35k re-reading an earlier batch's briefs and notes, ~14k its own retellings of refuter results and ~11k such diagnostics; a parallel session in another project read a 77 KB digest written for another agent (~35k) in full. Reading each drafted review before it is posted stays: that is a decision.
    • The user's own stale drafts are an assessment, not a review — change the deliverable, keep the discipline. When the target is a draft the user wrote (usually an AI-assisted retro or docs PR that sat for a week while main and sibling PRs moved), nobody needs a GitHub verdict; what the user needs is a per-hunk disposition so they can un-draft, rebase or close. Shape that worked (2026-10-08, three retro drafts): fetch the head into pr-<N>, run git merge-tree --write-tree --name-only origin/main pr-<N> for the conflict list, then classify every hunk against origin/main and against every other open PR by the same author (gh pr diff each one — several retro sessions write the same paragraphs) as KEEP / DROP (already on main, or carried by PR #X in equal or better form) / TRIM (time-bound clause) / FOLD (same line as a sibling — pick one carrier); verify each KEEP against current code, not the PR's own claims, because a week-old fact in a docs PR is a stale fact more often than not. The findings file keeps the normal header and severity codes for genuine defects (a wrong error message, a wrong § number, a future-dated amendment) and adds a Disposition per hunk table; the verdict names a path — rebase and trim, re-author on main, or close — and what would change it. Brief the refuter to attack the DROPs first (a false DROP loses a fact; a false KEEP ships a stale one) and to check the verdicts for cross-file consistency (one draft's "fold into #B" is void if #B's verdict is "close"). Nothing is posted to GitHub; the user reads the summary and decides. One timer for the batch, as above.
    • If the project uses an issue tracker (ClickUp, Jira, Linear, GitHub Issues, …) and the target references a ticket (e.g. CU-1234, JIRA-42, #123), pull it for context via the appropriate MCP if available — its scope informs the "does the diff do what the PR description claims" check.
  2. Gather inputs and check for prior CR rounds. Read everything relevant: all commits on the target, the PR description, all existing review and discussion comments (including author replies), and any prior findings files in docs.local/code-reviews/ matching cr-pr-<number>-*.md (PR targets) or cr-<slug>-*.md (branches/other targets). None of these reads depends on another, so issue them together in one message, along with the ticket and gh pr diff --name-only; only the fetch and the head check below run first and in order, before you read the diff itself.
    • If the PR is already merged, the review is a different job — say so up front and adjust. A post-merge pass is not a gate; its value is telling the reader what is still true of main today. Establish three states separately and never conflate them: the PR as merged, origin/main now, and the local checkout (which in a worktree is often behind both). Then, for every finding, check whether a later commit already fixed it — a follow-up ticket may have landed between the merge and your review, and re-raising a closed gap wastes the author's time and undermines the rest of the review. Say explicitly which findings are live on main and which are historical. Weight effort toward what someone could still act on.
    • No prior CR → proceed.
    • Prior CR exists → review only the new changes since (new commits, new discussion). Read author replies to prior findings carefully — don't re-flag what's been justified or resolved.
    • Prior CR exists and there are no new changes → tell the user and skip the CR; the author hasn't addressed earlier findings yet.
    • A new round belongs in a fresh session, not in the one that ran the previous round. Everything a round needs is durable: the prior findings files (whose header names the head SHA that round reviewed — the delta starts there), the PR's commits, comments and author replies on GitHub. Nothing has to be remembered from the conversation, so a fresh session loses nothing and starts at a fraction of the context. Keeping one session alive across rounds is what makes reviews expensive: a 30-day transcript audit (2026-10-01) found that sessions resumed after more than an hour's pause rewrote their whole context — often 400k tokens or more — into the prompt cache at twice the input price, 16–22 % of all tokens spent, and that every turn of a long-lived session re-reads that context; review rounds spread over days in one session were the typical shape. So when invoked in a session that already carries an earlier round of the same target, say so in one line and suggest continuing in a fresh session; then do what the user decides.
    • Compute the diff against the right base — don't trust the local checkout. In a CR worktree the local HEAD/main ref is often not on the PR commit and not on current origin/main (the session-start gitStatus is a stale snapshot, and repos with an auto-pin CI bot move origin/main independently). A raw git diff <local-main>...<head> can then show dozens of unrelated files. Always: git fetch origin (and git fetch origin +pull/<N>/head:pr-<N> for a PR), then review against the true merge-base — git merge-base origin/main pr-<N> — or just trust GitHub's own calculation via gh pr diff <N> and cross-check the file count against the PR's changedFiles. If the local diffstat and gh pr diff --name-only disagree on the file list, the local base is wrong, not the PR.
    • Check that pr-<N> is the PR's real head before reading it. Fetch with the leading + shown above: without it, a re-fetch after a force-push is refused as non-fast-forward and the old ref stays. Then compare git rev-parse pr-<N> with gh pr view <N> --json headRefOid --jq .headRefOid. GitHub updates refs/pull/<N>/head asynchronously, so right after a push it can still name the previous commit while the branch ref is already new. On 2026-10-27 a single git fetch output showed the PR branch moving to 19c8c866 and, two lines below, created pr-438 at the previous head 4d95e687; the review worked from the stale ref until it was caught and fixed with git update-ref. On a mismatch, re-fetch after a few seconds or fetch the head branch itself.
    • Infrastructure PRs (Terraform/OpenTofu, Kubernetes manifests): run the plan on a throwaway local merge of the integration branch into the PR head, never on the PR head alone. A PR branch is usually behind main, so a plan from its head "reverts" everything applied since the branch point and buries the PR's own changes in phantom noise (2026-09-24: the raw-head plan removed settings that were simply not on the branch yet). git checkout -b cr-<N>-merge-check pr-<N> && git merge origin/main, plan there, and compare the resource list against what the PR claims to add; delete the branch when the review is posted.
    • For a GitOps manifest change, work out per environment what the merge actually does before judging it. Two facts decide it, and the diff shows neither: the environment's sync policy (auto-sync applies the edit on merge; a manual-sync app waits for someone to sync it) and whether the image that environment is pinned to contains the code the change configures. They combine in ways the PR description rarely states. In one case (2026-09-25) a PR that set an SMS gateway env var and made its credentials Secret required reached three environments in three different ways. On the test environment, re-pinned on every merge, the feature really went live. Staging auto-synced the manifest at once, but its pinned release tag predated all the SMS code, so the env var was inert and the only live effect was a new hard Secret dependency. Production was manual-sync and unchanged until its cutover. Put that table in the findings file's summary: it is often the one thing the maintainer needs before merging, and it turns "is the Secret there?" from a guess into a scoped pre-merge check.
  3. Pick a CR title and start timesheet logging.
    • Decide a short, descriptive title for this CR.
    • If the user tracks time, start a new timer/entry for this CR using that title. Prefer the tracker-start / tracker-stop skills if available; otherwise use the timesheet tool the user has configured (Toggl MCP, Clockify, ClickUp time tracking — they may have specific instructions in their global or project instructions file).
    • If a timesheet session is already running, ask the user whether to stop it and start a new one for this CR, or leave the current one running. If it is stopped, do not stop it at "now" without looking. It is often another session's entry, and the work it describes may have ended hours ago. Find when that work last happened (the other session's transcript, its last commit or message), then stop the entry there, or tell the user the gap in the same message. On 2026-10-12 an entry covering three parallel tasks was stopped at the start of a CR after 7 h 48 min. Its sessions' transcripts showed about 1 h 45 min of activity, part of it overlapping review work already logged, and fixing it took a separate reconciliation later.
    • Between rounds, verification is CR work too. Answering "what's new on the PR?" between rounds usually means fetching and reading the delta — that reading is the next round's verification. Start the round-N timer before diving into the new commits, even when the formal round-N write-up comes later; otherwise the substantive work lands outside any entry and the formal round logs a misleading minute or two.
  4. Produce findings. Label each one with a severity code (C1, C2, M1, m1, n1, …). If a finding needs a new category (e.g. off-topic), propose it to the user with a suggested letter prefix.
    • Numbering continues across rounds; it does not restart. If round 1 ended at M1, m2, n2, then round 2's first new nit is n3. Restarting at n1 each round makes every reference ambiguous the moment anyone writes "the n1 you waived" — and rounds do cite each other, in the findings file, in the GitHub threads and in the author's commit messages. State the convention in the round's header so the author can see why the numbers begin where they do, and keep prior-round identifiers untouched in the Status of prior findings section.
    • Write the findings to a file in docs.local/code-reviews/ at the project root; content in English.
    • Filename: cr-pr-<number>-round-<N>.md for PR targets, or cr-<slug>-round-<N>.md for branches/other targets (slug = branch name lowercased and hyphenated, or another short identifier). Each review round is a new file — don't append to a prior round's file.
    • The file starts with a header: metadata (author, reviewer, date, PR/branch reference, round number, the head SHA this round reviewed) plus a short summary of the changes — in your own words, based on what you actually found in the diff (not a copy of the PR description).
    • A template is bundled with this skill — findings-template.md in this skill's directory — use it as a starting point.
    • Round 2+: include a ## Status of prior findings section in the new file listing every finding from prior rounds with its current status — resolved (author fixed it), still open (not addressed), or waived (author justified leaving it; include the justification). The latest round's file is then the canonical source of which blockers remain.
    • If docs.local/ doesn't exist, ask the user whether to create it (with the code-reviews/ subdirectory) and add docs.local/ to the project .gitignore. If docs.local/ already exists but code-reviews/ doesn't, just create the subdirectory.
    • Worktree-isolated session: write the findings file into the worktree's docs.local/code-reviews/ (create it; the .gitignore entry already covers it), since that is always reachable. Prior rounds may still live in the main checkout's docs.local/code-reviews/ — read them from there. Then, because the worktree's copy vanishes with the worktree, copy the file into the main checkout yourself at the end of the CR: a plain cp with absolute paths on both sides went through from inside a worktree on 2026-09-07, so do not assume it is blocked. Earlier revisions of this skill stated flatly that such a write "gets blocked by the isolation guard" and told you to hand the command to the user; that overstated it — the guard is about git operations and about paths it cannot statically verify, not about every write outside the worktree. If the cp is refused, then offer it to the user to run, still with absolute paths on both sides: a relative path assumes their shell sits at the repo root, and a worktree-relative cp .claude/worktrees/<name>/docs.local/… docs.local/ fails with No such file or directory, which reads as if the findings file were missing when only the command was wrong.
  5. Re-check severity. Is each finding labelled at the right level (Cx/Mx/mx/nx)?
    • Rate a finding by what the PR changes, not by how bad the underlying problem is. Before calling a security finding Major, check the base: is the weakness new, or does the PR partly fix something that was worse before it? In one case (2026-09-25) a PR masked a secret in the audit log, but the library's default mask kept the second half. That was first rated Major. The refutation pass pointed out that the base had logged the whole secret, and that the same value sat in plaintext in its source table anyway. So the PR had reduced a leak, and the finding was that its comment and test claimed more than the code did: Minor. An inflated tier turns a sound PR into a Request-changes round and teaches the author to discount the tiers.
    • Weaknesses the review surfaces outside the diff get their own section and their own route. List them under a separate prefix (e.g. P1 for pre-existing), outside the C/M/m/n counts, and hand them to the maintainer instead of the PR author, since they are not the author's to fix in this PR. When one describes where live secrets or personal data can be read, keep the detail out of the public PR thread: one sentence there ("older masking issues found, tracked separately"), details in the private tracker.
    • "Nothing for you to do here" is only true if someone else now owns the item. Before posting, file each P item in the tracker, name who will, or drop it explicitly. A P item told to the author as nothing-to-do and then filed nowhere has no owner at all: on 2026-10-08 a second round found two such items from the first round, untracked and still open.
  6. Re-check for false positives. Common. Remove the finding or downgrade its severity.
    • A claim about infrastructure state is not a fact just because you remember it — verify it live or date it. The riskiest sentence in a finding is usually the one that makes it land: "this will put X back into a degraded state, and that signal was deliberately cleaned up". On 2026-09-16 that sentence went into a review comment to an external contractor while the component in question had already been degraded for a day, for an unrelated reason — and the session's own notes said so, in the same file as the older line it quoted. The argument survived; its strongest clause was false. So before asserting anything about what is deployed, healthy, synced or running, either check it now, or write the claim with its source and date ("per a note from 2026-07-29, unverified today"). If you have no access to check (no tunnel, no kubeconfig), the honest form is "I have not verified this" — not silence about the gap. Notes about component health decay in weeks.
  7. Add line references to each finding where it makes sense (file:line or file:start-end).
  8. Add a fix snippet to each finding where it makes sense — a code change the author can apply with one click.
  9. Re-verify line numbers against the actual file state; they often drift between earlier passes.
  10. Second verification pass: for each finding, re-check severity, false-positive risk, line references, and suggested code.
  11. Third verification pass: final check of everything to avoid wasting the author's time on inaccuracies.
    • Then an adversarial refutation pass in a fresh context. Dispatch a subagent on the strongest available model tier (e.g. Claude Opus, OpenAI Astra) with ONLY the findings file and the diff (not your reasoning or verdict), briefed to refute each finding and to look for what the review missed. Hand it the review's "verified rather than assumed" claims as explicitly as the findings, and ask it to attack those too. A wrong premise moves every tier at once, so it is worth more to the author than a wrong finding: on 2026-09-29 a refuter left all four findings standing and instead refuted the review's claim that no deployed environment ran the changed code — which was the whole reason the review had called everything a nit. The tiering happened to land correctly, but it had been resting on a false sentence, and nothing in a findings-only brief would have caught it. A reviewer handed conclusions returns validation of those conclusions; a refuter finds the gaps. Record the outcome per finding in the findings file (stands / downgraded / refuted / new). On 2026-09-24 this pass produced the review's only staging-visible finding — the three earlier passes had walked past it. A delta round is no exception, least of all when the author applied your own suggestions verbatim. The reviewer then tends to read "verbatim" as "correct" and reports nothing new; on 2026-10-09 ten such delta reviews came back clean and the refuters found an error in the reviewer's own previously posted text — a runbook step, a code comment, a client-side fix, a test helper — in six of them. Brief the refuter to attack the text you suggested before anything else.
    • For a PR that gates, permits, or filters something (auth, feature toggles, tenant isolation, permissions, rate limits), run a second refuter, also on the strongest tier, that gets neither the findings nor the diff's rationale — only the artifact and the contract it must satisfy — briefed to break the contract, not to check the review. Neither refuter needs the other's result, so when both run, start them together. A refuter given findings re-litigates them; one given only the contract finds what no finding named. Seen 2026-09-14: this pass surfaced two material facts that three self-verification passes had missed, both about what the gate actually enforced rather than what the diff said it did.
    • Every review agent's brief forbids requests to external services, in so many words. That means third-party APIs (an SMS or payment provider), object storage, secret managers and any deployed environment, unauthenticated probes included. A question about how a provider or a client library behaves is settled from the library's source, the provider's documentation or a local stub; if none of them settles it, the finding says "not verified". The rule has to be in the brief because an agent told to break something reaches for the real thing: on 2026-10-12 a refuter checking whether an HTTP client followed redirects sent a POST to a live SMS provider's production API. It got a 401 and nothing was sent, but nobody had approved a request to that system, and the brief had not said it was off limits.
    • Two fixes that were each verified are not verified together. When the review recommends more than one change to the same code path, run them combined. And give whoever drafts the posted text the job of re-checking every snippet against the head: on 2026-10-08 that step found two separately verified fixes that combined into a job silently holding rows, and a suggested template change that broke the component's element references. Each layer — reviewer, refuter, drafter — caught an error the previous one had passed. Brief the drafter, too, to keep every runtime claim tied to the tree it ran on: "the suites pass on the merge result" is true of the integration branch as of the day the run happened, and when the review is posted days later the sentence has to say that day. On 2026-10-26 a drafter merged "the branch still merges cleanly (re-checked today)" with a three-day-old test run into one sentence that read as if the tests had run that morning.
  12. Freshness re-check. Re-fetch the target's commits and comments. If anything is new since you started the review (a new commit, a new comment, a new reply), extend the review to cover the new content — pass through steps 4–11 for the new material and revise existing findings in light of any new context — before continuing.
  13. Summarise to the user — e.g. 4 critical (C1,C2,C3,C4), 3 major (M1,M2,M3), 2 nits (n1,n2), mention the docs.local/code-reviews/ file with the full CR, and wait for the user's go-ahead. If there are no findings at all, summarise briefly as LGTM and offer immediate Approve. If there are no Cx/Mx blockers, also offer the "approve & merge" option (see step 14) — and say in the same breath what reply authorises the merge (e.g. "to merge too, answer merge it"). A picked menu number is a preference, not a merge directive (merge-pr step 1), so an offer that does not name the words costs a second round trip: on 2026-10-02 the user answered "2" to an "Approve + merge" option and then had to repeat "squash-merge it" before anything could happen.
    • An open question that routes a decision outward is a claim; check it before you pass it on. When a reviewer, refuter or drafter writes "this goes to the CTO", "someone must confirm X with the client" or "the PM should decide", check two things first: the rule it rests on, and how big the risk is. Then ask whether a different fix would make the escalation unnecessary. A message sent to a stakeholder or client costs their time and the user's credibility. On 2026-10-29 the user's "why?" settled both such questions in one batch. A refuter routed an ADR wording question to the CTO, citing the rule that changing an ADR's meaning is CTO scope. Reading the ADR as the cap it describes, and keeping the lock length out of the ADR text, left no change of meaning and so nothing to escalate. A reviewer's "who confirms fixed file names with the client?" turned into a drafted message to the PM. The user's three questions (how long the processing window is, whether the file stays afterwards, whether anyone would overwrite it) showed the risk needed a same-name upload during one import run plus a manual run, and the message was dropped.
  14. After approval, post to GitHub (skip this step if the target is not a GitHub PR — the findings file is then the only deliverable):
    • Each Cx and Mx finding → its own inline comment (or a standalone comment if inline isn't possible).
    • mx and nx findings: default to the summary list (next bullet); inline is OK when the location really helps the author find the spot.
    • A summary comment with: an overview of all findings (including counts/lists for mx and nx), thanks to the author, praise where deserved (skip rather than force a generic line), and clear instructions — what must be fixed (Cx, Mx), what should be attempted if easy (mx), and what is optional (nx).
    • An Approve with minors you still want fixed must say so in words. "0 critical, 0 major" next to a green Approve reads as "done", and a list headed "still open (none blocking)" reads as optional. When the user wants the mx items resolved before the merge, the body says it in one sentence ("please resolve m1–m8 before we merge; if you disagree with one, reply under it"), and the review-state label stays on the author. On 2026-10-26 a round-2 Approve listed eight open minors as "none blocking"; the user had to ask for a follow-up comment before the author could know they were expected.
    • PR title / description nx findings: include them in the summary comment as recommendations (GitHub has no inline slot for title or description).
    • All GitHub comments in English.
    • Partial-scope review → Comment, not Approve. When the user asked for only part of the PR (e.g. "just the infra part"), open the summary with the scope you actually read and say what you did not; submit the review as a COMMENT even with zero blockers, because a green Approve reads as a sign-off on the whole PR. Offer Approve only if the user explicitly wants the scoped verdict to carry that weight.
    • Approve & merge: only if all four hold — (a) no Cx/Mx findings remain unresolved across all rounds (check the latest round's Status of prior findings plus its new findings), (b) CI is green (treat a failing or pending CI as a blocker → don't merge; report the failing checks to the user instead), (c) the repo's required approval count would be met after your Approve (if not, still submit the Approve verdict but don't merge — tell the user how many more approvals are needed), and (d) the user pre-authorised it together with the go-ahead in step 13 — in words that name the merge, not by picking an option number. If all four hold, after posting the comments also submit an Approve verdict and merge the PR using the repo's default merge button setting (squash / merge commit / rebase — ask the user if unsure).
    • When the user decides to fix the findings in the author's branch instead of waiting for the author (to land the PR the same day): implement from the final findings file only after the refuter passes, one implementer agent per PR — each in its own isolated worktree when two run at once — committing locally; read its diff and push yourself. This is only for a branch in the same repository: a fork belongs to its owner. Merge the integration branch into the PR branch rather than rebasing, so nothing is force-pushed onto someone else's branch and CI plus any automated reviewer run on the real merge result, and check that the remote head is still the reviewed one immediately before the push. Re-run every runtime check with all the fixes together: on 2026-10-22 a storage-configuration fix that passed on its own failed once the full test set ran on the same store. The posted review is then an Approve whose body lists each fix with its commit SHA and what is left for the author, so the author can pull and see exactly what changed in their branch.

14b. A merge is a sequence, not a button — run the merge-pr skill for it. "Merge it" authorises the whole sequence, and the steps after the merge are the ones that get forgotten: a squash body nobody wrote (the default is the branch's own commit messages, Fixed review notes included), labels left on a merged PR, the author's other open PRs silently put into conflict in some shared paragraph of prose, branch cleanup that does not apply at all to a fork PR, and a tracker task claiming the wrong person is on the hook. merge-pr carries all of it plus the pre-flight (head SHA still the reviewed one, checks per job, .github/workflows/* needing a different merge tool). Do not restate it here — one source of truth. If that skill is not installed, do the sequence by hand and say in the report which parts you covered.

  1. Stop the timesheet entry once the CR work is complete — whether after posting (step 14), after a non-PR target's final summary (step 13), or if the user declined to proceed.
    • A go-ahead can take hours, and waiting is not review work. Stop the entry when you hand over the summary in step 13, and start a fresh one for the posting/merge sequence when the answer arrives. Otherwise one entry silently spans a lunch break and the timesheet has to be corrected retroactively — which costs more than the two extra calls.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.