agentleFS
TomSzenessyTomSzenessy/AI_TEMPLATE/.agents/skills/review-practice/SKILL.md

review-practice

Skill0 starsChanged 11 days agoMITView on GitHub

How to request, give, and receive code review in this repo (what to send the critic, review axes with severity, terse path-and-line findings, verifying feedback before implementing it); Use when work needs review before merge, you are asked to review a diff or PR, or you received review comments and must respond.

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 6 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Do not invent others (no "approve", "LGTM", "needs work").

    line 14
  2. Very specific:

    Do not review your own large diff inline: it burns the context you need to keep driving, and you cannot falsify your own work.

    line 32
  3. Distinctive:

    Read in this order:

    line 39
  4. Distinctive:

    Tests first: do they pin behavior (not implementation), cover edge and error paths, and have names that state the behavior?

    line 42
  5. Distinctive:

    Read all of it: before reacting.

    line 111
  6. Distinctive:

    Clear up the unclear first: If any item is ambiguous, ask about it before implementing anything.

    line 112
  7. Distinctive:

    No performative agreement: never "you are absolutely right", "great catch", thanks, or "implementing now" before verifying.

    line 131

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “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 practice

Three jobs: request a review, give one, receive one. Roles and verdicts are owned elsewhere: the independent reviewer is the critic role, briefs and returns follow docs/delegation.md, and the only verdict words are the two defined in its verdict section. Do not invent others (no "approve", "LGTM", "needs work").

Request a review

When: make risk says high; before merge; after a complex or security-relevant fix; when the work is subjective or has no command oracle; when stuck and a fresh view helps. Commit first, so the critic reads a real Commit:.

Send (precise context, never your session history or your theory of why it is right):

  • Issue or the acceptance criteria verbatim.
  • Diff as a range: git merge-base origin/main HEAD to HEAD.
  • Artifact to open (rendered page, output file, API response).
  • Scope of readable paths, and Done when.
  • Missing pieces? make review-packet ISSUE_FILE=<path> builds the packet.

Do not review your own large diff inline: it burns the context you need to keep driving, and you cannot falsify your own work. Delegate, read the return block, act on Blockers, record per delegation.md. A reviewer never spawns reviewers and never edits; it returns findings.

Give a review

Read in this order:

  1. Intent: what is this change for, what is the acceptance bar?
  2. Tests first: do they pin behavior (not implementation), cover edge and error paths, and have names that state the behavior? Probe it: invert one condition the change adds, run the suite, restore the file. Tests that still pass do not guard that line.
  3. The code, against five axes:
    • Correctness: matches spec, edge cases (null, empty, boundary), error paths, races, state consistency. Silence in the spec is not permission: judge by what a reasonable user would expect.
    • Simplicity: could this be fewer lines or fewer concepts? Abstractions earning their keep (not before a third use)? A new conditional bolted into an unrelated flow, repeated conditionals on one shape (missing model), dead code, compat shims, near-duplicate helpers? A refactor that leaves the concept count unchanged only relocates complexity.
    • Architecture: follows existing patterns (new ones justified), owner boundaries respected, no feature logic leaking into shared modules, dependencies one-way, explicit type boundaries instead of casts and silent fallbacks. Name the remedy, not just "this is complex": extract, collapse duplicate branches, delete a pass-through wrapper, move to the owner.
    • Security and privacy: untrusted input validated at boundaries, secrets out of code and logs, authz where needed, parameterized queries, output encoded, dependencies vetted (docs/security.md).
    • Performance: N+1, unbounded loops or fetches, sync work that should be async, hot-path allocation.
  4. Verification story: which commands ran, was the real artifact observed, do docs bound by <!-- covers: --> match the change?
  5. Size: around 100 changed lines reviews well, 300 only as one logical change, 1000 means split. A refactor mixed with a behavior change is two changes.

Approval standard: ship when it clearly improves code health and meets acceptance, even if imperfect. Do not block on taste. Do not pass what you have not run.

Severity

TagMeaningCritic mapping
bugBroken behavior, security hole, data loss, unmet criterionBlockers
riskWorks but fragile: race, missing check, swallowed error, no testBlockers if it can hurt users, else Residuals
nitStyle, naming, micro-optimisation; author may ignoreResiduals or drop
qGenuine question, not a suggestionanswer before verdict

Lead with highest leverage: correctness and security, then structure, then cosmetics. Do not bury a real issue under nits.

Finding format

One line each: path:line — problem — fix, with a severity tag when mixed. Exact symbols in backticks; a concrete fix, not "consider refactoring"; no hedging ("maybe", "I think": use q), no praise per line, no restating what the line does.

src/auth.py:42 — bug — `user` can be None after `.find()`; guard before `.email`.
api/list.py:23 — risk — no retry on 429; wrap in `with_backoff(3)`.
util.py:88-140 — nit — 50-line fn does 4 things; extract validate/normalize/persist.

Drop terseness for security findings, design disagreements, and a new author who needs the why: write a short paragraph with the evidence, then resume.

Also list anything you considered but set aside as out of scope, one line each with the reason, so the owner can rule on it. Return in the critic block format.

Receive a review

Applies to a critic return, a human comment, or an external bot.

  1. Read all of it before reacting.
  2. Clear up the unclear first. If any item is ambiguous, ask about it before implementing anything; items interact, partial understanding gives wrong work. "Understand 1, 2, 3, 6. Need clarification on 4 and 5."
  3. Verify each item against this repo: reproduce the bug or read the code. Is it correct here? Does it break something? Why is it written this way (git log -p, make where)? Does the reviewer lack context? Does it conflict with a recorded decision in an issue or ADR? Cannot verify: say so and ask.
  4. Push back with evidence (a test, a path:line, a command output) when it is wrong, breaks behavior, or is unused ("grep finds no callers; remove instead of extending?"). Architectural conflict: escalate to the owner, do not decide silently.
  5. Implement one item at a time, ordered blockers (breakage, security), then simple fixes, then complex ones; run the focused check after each, then make done. Re-request the critic if a blocker changed code.
  6. Reply in the thread (GitHub: reply to the comment, not top-level) with the fact: "Fixed in path:line: <what>". If your pushback was wrong: "Checked X; it does Y. Fixing." No apology essay.

No performative agreement: never "you are absolutely right", "great catch", thanks, or "implementing now" before verifying. Actions and evidence are the response.

ExcuseReality
"The reviewer is probably right, just do it"Unverified changes add bugs; check first.
"Implement the clear ones, ask about the rest later"Unclear items can change the clear ones.
"Its tests passed, so the feedback is moot"Passing proves what ran, not what was missed.
"I will review my own diff, it is small"Same blind spots as the author; use the critic at high risk.
"Add the proper version it suggests"Check use first; unused code stays unbuilt.

Ponytail (make upstream ID=ponytail-lazy-senior): a smallest-change discipline plus a ranked audit and a shortcut-debt ledger. Pull its ponytail-audit file when a review keeps finding over-built code. Skip it when the diff is already minimal.

Addy agent-skills (make upstream ID=addyosmani-agent-skills): long security, performance, accessibility and testing checklists. Pull the one whose axis the diff changes (auth, a hot path, UI, test strategy); skip axes the diff does not touch.

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.