agentleFS
stormlightlabsstormlightlabs/thunderus/.claude/skills/review/SKILL.md

review

Skill4 starsChanged 57 days agoApache-2.0View on GitHub

Review a pull request or branch and post findings as comments. Runs a standard pass or an adversarial pass. Use for /rev, /adv-rev, code review, PR review, or when asked to check a diff for defects before merge.

192 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

  • LambenthanSkill

    daily-arxiv

    每日从 arXiv 拉取新论文,过滤相关性,auto-ingest 高优先级论文,检测 SOTA 更新

    Also in 5 projects that use this

  • LambenthanSkill

    exp-eval

    实验判决门:Review LLM 独立评判实验结果 → 4 种判决路径 → 自动更新 claims confidence、ideas status、graph edges

    Also in 5 projects that use this

  • +3 more from dzhng
  • +5 more from Lambenthan

The file

We split this skill into the rules it gives an agent

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

  • 0

    Common

    Most of the 157 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read the changed files around the diff, not only the diff.

    line 57
  2. Very specific:

    Use the transport the github-board skill's Transport section names, gh or the GitHub MCP tools, for the whole pass.

    line 63
  3. Very specific:

    Do not read the change with Read, Grep, or Glob, and write nothing inside the repository.

    line 68
  4. Distinctive:

    Ask before posting when no pull request is open, and never post to a repository the user did not name.

    line 187
  5. Distinctive:

    Do not repeat a finding an earlier pass raised and an edit pass addressed, whether it was posted to the thread or handed to you by your …

    line 193
  6. Distinctive:

    If the same finding survives two edit passes without the cause changing, stop and escalate to the user rather than posting it a third time.

    line 195

“Common” is measured: kept by at least 6 in 10 of the 157 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

Review

Review a diff and post findings. Do not edit code during a review pass. The /edit command owns changes.

Pick the target and the pass

The argument is a pull request number, a branch name, or empty. Empty means the current branch.

PassCommandBrief
Standard/revCorrectness, edge cases, security, concurrency, performance, API compatibility, test coverage, readability.
Adversarial/adv-revWorst case only: security holes, races, unhandled input, violated invariants, tests that cannot fail.

An adversarial pass assumes the standard passes already ran. It looks for what they would miss, not for the same findings again.

What the adversarial pass owes

The standard passes read the change as written. The adversarial pass reads it as hostile input, an unlucky interleaving, or a caller who ignores the documentation would.

.claude/agents/adversarial-reviewer.md lists what it hunts and what it owes each finding: a named input, ordering or state, and how far you got. One rule is worth repeating here because it is the one that inflates a comment — prefer a few findings you can support to a list you cannot. One proven race changes the diff; six guesses cost the next editor a day.

Complexity

Both passes weigh complexity, because a defect is cheaper to prevent than to find. Ask of each change:

  • Is this harder than the problem it solves? Name the simpler version and what it would cost.
  • Does it add a trait, a layer, or a configuration point that one concrete helper would cover? CLAUDE.md asks for traits only at real boundaries.
  • How many things must a reader hold at once to know this is correct? A branch nested inside a closure inside a retry is three.
  • Does it repeat something the codebase already does, under a new name?
  • Could a check replace the care this asks of the next person to touch it?

Report complexity the way you report a defect: what it costs, and what to do instead. "Simpler would be better" without a concrete alternative is not a finding. A change that is merely longer than you would have written it is not either.

Gather context first

Read the changed files around the diff, not only the diff. Read the issue the pull request closes. Read CLAUDE.md for the rules the change must satisfy.

Four rules govern how a pass reads, and references/reading-the-diff.md gives the commands and the reasons:

  • Use the transport the github-board skill's Transport section names, gh or the GitHub MCP tools, for the whole pass.
  • Fetch the branch first. A shallow cloud clone usually does not have it.
  • Pin the head commit once and review that commit, so every finding describes one state of the tree.
  • Do not read the change with Read, Grep, or Glob, and write nothing inside the repository. Both reach whatever branch the checkout sits on.

Judge against something

A finding needs a source. Rank them:

  1. The issue's acceptance criteria.
  2. The rules in CLAUDE.md: module order, error policy, trait boundaries, the documented-invariant requirement for unwrap, expect, panic!.
  3. Tests that exist, tests that should exist, and tests that cannot fail.
  4. Behavior a user can observe.

Taste alone is a nit at most. Model disagreement is not a finding.

Prose in the diff

A diff touching docs/, internal/, README.md, CHANGELOG.md, or .claude/ is a change under review like any other. Judge its prose against the writing-docs skill.

What you findSeverity
Documentation contradicts the code it describeshigh
User-visible behavior changed, documents did notmedium
Past a soft limit or a length targetlow
Writing tells, heading case, term driftnit

Length is a finding when a reader reaches the answer only by scrolling past something that repeats the code, the tests, or another page. Name that part and what it repeats. "Too long" on its own is not a finding.

Finding format

One line per finding:

<severity> · <path>:<line> — <problem> → <why it matters> → <fix direction>
SeverityMeans
blockerMerging causes data loss, a crash, a security hole, or a regression.
highWrong behavior in a case the change is supposed to handle.
mediumWrong behavior in an unhandled case, or a missing test for one.
lowWorks, but will cause a defect later.
nitStyle or naming inside the repository's conventions.

State what breaks and with what input. A finding that cannot name a failing case is speculation; drop it or mark it nit.

Keep the report readable

  • One line per finding, most severe first. No preamble, and no closing section restating the lines above it.
  • Under 200 words, counted in words because GitHub soft-wraps a comment and a line count there measures nothing. Past ten findings, give the ten that matter and say how many nit rows you left out. Cut a finding rather than compressing ten into denser prose.
  • Cite <path>:<line> instead of quoting the diff back at its author.
  • Group repeats. One finding naming every site beats one finding per site.
  • Report findings and nothing else, to the thread and to whoever invoked the pass alike. Branch state either can see, such as the base branch having moved, is not a finding.

Which passes post

Findings go to whoever invoked the pass, in full, every time. The question here is only which passes also comment on the pull request.

PassComments on the pull request
First standardNo.
Second standardYes, on what survived the first, or to say nothing did.
AdversarialYes, including to say it found nothing.

A first pass does not comment because most of what it finds is fixed within the hour, and a reader scrolling through resolved findings learns nothing about the change. What outlived a round of fixes is the part worth recording. An adversarial pass is the last thing before a human reads the diff, so the record has to show it ran.

The invoker says which pass this is; /rev takes it as an argument and the thunderstorm skill fixes it at dispatch. Do not infer it from the thread, which gets it wrong: a pass that found nothing leaves nothing behind, and a comment can be edited or deleted. Where no pass is named, this is a first pass.

A pass that posts nothing still owes its findings to the invoker, because they are the next /edit pass's only input. An orchestrator hands them to /edit and to the second pass both: "what survived the first" is not something the second pass can work out, having never seen the first.

Post the findings

Post one comment per pass, not one per finding, under 200 words. Open it with one line carrying which pass this is, what it read, and what it ran as:

Second standard pass on #12 at 4f2a91c · claude-opus-5 · high

The pull request as well as the commit, because the branch is deleted when its pull request merges and a review citing only a SHA is unreadable by the time anyone goes back to it. The model and level because internal/models.md sets which model runs which pass, and this line is the only record that check can read afterwards. Use the identifier the harness reports, not a friendly name.

That line is the whole ceremony. Nothing goes at the bottom: the harness appends its own footer, and a signature under it was displaced in 54 of the 57 comments this repository has posted.

Two hundred words is ten findings at one line each. When they do not fit, cut a finding and say how many you left out. Do not compress ten into denser prose.

gh pr comment <n> --body-file <file>
# MCP: add_issue_comment with issue_number set to the pull request number.

Ask before posting when no pull request is open, and never post to a repository the user did not name.

Stop conditions

  • Report No findings rather than inventing something to justify the pass.
  • Do not repeat a finding an earlier pass raised and an edit pass addressed, whether it was posted to the thread or handed to you by your invoker.
  • If the same finding survives two edit passes without the cause changing, stop and escalate to the user rather than posting it a third time.
  • Cap a review-and-edit cycle at 5 rounds.

Do not

  • Edit files, commit, push, approve, or merge.
  • Review a diff you wrote in this same session without saying so in the comment.
  • Weaken a test to make a finding go away. That belongs to /edit, and it is not permitted there either.

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.