local-review
Skill4 starsChanged 49 days agoMITView on GitHub
Review the current branch's diff locally BEFORE opening or updating a PR, so external reviewers (CodeRabbit, Codex, humans) find nothing you could have caught yourself. Use when asked to review local changes, before commit-push-pr, or when about to open a PR. Applies a lens checklist grown from real review findings; report findings with concrete failure scenarios, fix them, and re-run until clean.
7 other projects use a version of this.
Adopted by
Most recently taken up by
- lablup/backend.aitheir own version, first seen Nov 9, 2026
- Pubx-ai/skillstheir own version, first seen Nov 8, 2026
- davisbuilds/dojotheir own version, first seen Nov 1, 2026
- oracle/mcptheir own version, first seen Oct 17, 2026
- fedemelo/agent-configtheir own version, first seen Oct 17, 2026
- windmill-labs/windmilltheir own version, first seen Oct 8, 2026
Other versions7 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 7
- windmill-labs/windmill★ 19ksame name
- lablup/backend.ai★ 681same name
- oracle/mcp★ 483same name
- Pubx-ai/skills★ 6same name
- fedemelo/agent-config★ 4same name
- khou/skills★ 1same name
- davisbuilds/dojo★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository5 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- pall8tSkill
- releaseSkill
- review-loopSkill
- pall8t-herdrSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. 0 are common, 7 are distinctive, and 6 are very specific to this project.
0
Common
Most of the 6 edited versions we read keep these.
7
Distinctive
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 9
Every finding a bot catches after push is one this review should have caught before it.
- Distinctive: line 21
Before reading anything, run the machine's share — style and lint findings are its job, not this review's:
- Distinctive: line 34
Read the full diff once for orientation, then pass through the lenses below.
- Very specific: line 67
A deprecation/ignored-setting warning is itself user intent: check which commands reach the print.
- Very specific: line 126
When a limit constant is spelled out in more than one walk, check they actually agree — off-by-one between "the list we offer" and "the …
- Very specific: line 168
Read the consumer's parser before deciding what is safe (split(":"), maxSplits, whether extra fields error or are silently accepted).
- Very specific: line 195
Do ADR/README/skill statements match what the code does *in the degraded paths* — missing optional dependency, failed setup, mode switched …
- Very specific: line 260
Read-only mounts broke *linked git worktrees* as reference repos — their .git is a pointer file to a path outside the source — precisely …
- Distinctive: line 265
Check identity, permissions, and ownership across the boundary, not just the behavior you were aiming at: apple/container applies its …
- Very specific: line 270
Verify the new default on the real runtime with the tool the users use (git, not cat).
- Distinctive: line 275
Before writing what happens to something "at the end of the run" — discarded, cleaned up, disposable, temporary — find the code that …
- Distinctive: line 290
Read the section header above an inserted entry, not just the diff hunk.
- Distinctive: line 377
When an external reviewer (bot or human) later finds something real that this review missed, don't just fix it — generalize it into a lens …
“Common” is measured: kept by at least 6 in 10 of the 6 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.
Files
Local review
Goal: the external reviewers on the PR should come back empty-handed. Every finding a bot catches after push is one this review should have caught before it. When one slips through anyway, this file learns it — see "Grow the lenses" at the bottom.
0. Scope and mechanical gates first
git diff --stat origin/main...HEAD # committed changes
git status --short # uncommitted / untracked tooReview everything that will end up in the PR, not just the last commit. Before reading anything, run the machine's share — style and lint findings are its job, not this review's:
scripts/lint.sh && cargo testFor nontrivial logic changes, also spot-run mutation testing on the
changed files (cargo mutants -f src/<changed>.rs) — a test that
wouldn't go red is a finding.
1. Review through each lens
Read the full diff once for orientation, then pass through the lenses below. A finding must name a concrete failure scenario (inputs/state → wrong outcome); "this looks risky" without one is not a finding. These lenses are generalized from real external-review findings that local review failed to catch first (source PRs noted).
Policy and trust boundaries (PR #38)
- Any allow/deny decision: is the default direction safe when the input is unknown or novel? An enumerated denylist silently allows the next thing an upstream adds — prefer default-deny by namespace/class with explicit carve-outs, or document why transparency wins.
- New listeners/endpoints: bound as narrowly as possible (specific
interface, not
0.0.0.0)? Who can reach it besides the intended peer, and what gates them? - Anything downloaded and later executed or mounted: integrity-verified on every use, not just at fetch time? Where does the verification record live — can the thing being verified overwrite its own record?
- Fail open vs fail closed: when setup fails partway, which side does the feature land on, and does the user find out?
Silent fallbacks (PR #38, #43)
- Config parsing: does a misspelled key/value fall back silently to a
default — and is that default the permissive one? Security-relevant
settings must fail the parse (
deny_unknown_fields), not degrade. - Any
unwrap_or(default)/.ok()on user intent: same question. - Type-narrowed presence checks (PR #43): a check that asks "is this
setting present?" through a type filter (
as_table(),as_str(),downcast, a match on one variant) answers "absent" for every value of the wrong shape.home = "isolated"is a plausible miswrite of[home] mode = "isolated"; narrowing withas_table()made it invisible. Enumerate what the user could plausibly have typed, not what the happy path expects — and when the branch exists to tell the user something, the wrong-shape case usually needs telling too. - A deprecation/ignored-setting warning is itself user intent: check
which commands reach the print. A warning only wired into the main path
is silent exactly where a confused user looks first (a
doctor-style diagnostic).
Config a repository can ship (PR #63)
- pall8t merges a project's
.pall8t/config.tomlover the user's global one, per field. That file arrives with the repository, so for any new setting ask: if a repo I cloned set this, what would it get? Sort the setting first — does it shape what runs inside the sandbox (command, image, mounts it needs), or does it widen what the sandbox reaches outside itself (credentials, host sockets, bridge policy)? The first is the project's business. The second must take the human's global config or an explicit flag, andproject.or(global)is the wrong merge for it —[container] ssh = truein a cloned repo would have handed that repo the user's SSH agent. - Narrowing is always safe to honor; widening is the direction that needs an owner. A setting that can only be turned off by the project needs no gate.
- Refusing is half the fix: a dropped intent must still be reported, or the silence hides that the repository asked at all.
Fallback to a secondary tool (PR #50)
- A fallback that invokes a manager/helper tool (
rustup,nvm, a package manager) to repair the active environment must first check the tool actually governs that environment — presence on PATH is not governance. Enumerate the split-brain states: manager present but managing nothing (its commands fail, and underset -ethat aborts the script on exactly the path meant to be forgiving), and manager managing a different copy than the one on PATH (the "fix" lands where nothing reads it). lint.sh hit both with a leftover rustup next to the nix toolchain; the check that ties them together is whether the active tool's root (rustc --print sysroot) lives under the manager's home.
Docs the diff touches (PR #43)
- Markdown lint is part of the review even when CI doesn't run it:
adjacent blockquotes separated by a blank line (MD028) is the one this
repo has actually hit, from prepending a banner to a doc that already
opened with a
>note. Continue with>rather than deleting the blank line — deleting it merges two distinct notes into one paragraph. - A banner or status line added to a doc must not contradict a claim further down the same doc, or the ADR/CHANGELOG describing the change.
Guards that infer ownership from current state (PR #72)
- A guard that decides "may I overwrite this?" by reading the value as it stands now cannot recognize the writes it made itself on an earlier run — so it protects only the first pass, and every run after it takes the wrong branch. pall8t skipped renaming a tab whose label wasn't herdr's auto label; after its own first run the label was no longer the auto one, so run 2 read its own handiwork as a human's and left the tab pointing at a name that by then belonged to a different agent. Enumerate the second run explicitly, not just the first.
- Where the actor can't tell its own past writes apart from a third party's (the derivation changed between runs, so the old value is unreachable), the residual case doesn't disappear — decide what the user is told. Silence there means the divergence is created without anyone seeing it.
Two sites claiming the same bound (PR #72)
- When a limit constant is spelled out in more than one walk, check they
actually agree — off-by-one between "the list we offer" and "the list
we try" is invisible in review and in normal runs.
candidatesyieldednameplus2..=N(N names); the retry loop ranfor counter in 2..=Naround a mutable accumulator and tried N-1. Prefer one iterator both sites share; where they can't share, a test asserting equal length is the pin.
Probes that decide destructive actions (PR #62)
- A health/liveness probe whose "no" triggers a delete, kill, or unlink
must distinguish the peer answered no from the probe failed to ask.
connect(…).is_ok(),exists(),ping == 0, a nonzero exit — each collapses both into one bit. Enumerate the errnos:ECONNREFUSEDand "not found" mean gone;EMFILE,EACCES, a timeout mean the prober is having a bad day, and acting on those destroys live state (a running sandbox's bridge socket, in the case that named this lens). Unknown must fall on the keep side, the way an unreadable mtime already does. - The same rule scales down: any
unwrap_or(false)on an IO probe is a policy decision about the failure case, so state which case it is. - Probe the property you are claiming, not its cheapest proxy (PR #63).
A probe answers the question it asks, and
exists()asks about an inode, not about a peer — so a socket whose agent wasSIGKILLed (or outlived by the tmux session still exporting its path) passes an existence check and refuses every connection. No reboot, no unlink, so the "stale" case the warning was written for was the one it stayed silent on. Name the property in the predicate —agent_reachable, notsock_exists— and the gap gets hard to write down:connect(2)separates listening from dead node from unlinked, where oneexists()collapses all three. Applies to any liveness claim built from a proxy: a pidfile is not a running process, a port in a config is not a bound listener, a lockfile is not a held lock. - The tell in review is a doc/comment that claims more than the predicate
delivers. Read the two against each other: when the prose says "a socket
that died with its agent" and the code says
Path::exists, the prose is describing the intended probe and the code is the one that ships.
Interpolating into a delimited wire format (PR #62)
- Building
a:b,k=v,x,yfor another process? The delimiter must be rejected (or escaped) at the boundary that constructs the value, not asserted in a comment. Two real ones in one PR: a:in$HOMEturns a two-field-v host:guestinto a three-field one whose third field is parsed as mount options, and an=in a project path makes apple/container's label parser throw and fail the whole run. - Read the consumer's parser before deciding what is safe (
split(":"),maxSplits, whether extra fields error or are silently accepted). "This form has no third field to mistype" is a claim about inputs, and only becomes true when something enforces it. - Values that can't be escaped (paths) get a guard that fails the feature; values that can be sanitized (labels, display strings) get sanitized — never let provenance metadata break a launch.
Internal and hidden entry points (PR #62)
#[command(hide = true)]hides a subcommand from--help; it does not stop anyone from typing it. If the command chmods, unlinks, or sweeps a directory, validate that the directory is the one it is supposed to own before doing any of it —--listen /tmp/x.sockshould not chmod/tmpto 0700 on its way to failing.- Spawned children on error paths: a
bail!betweenspawnandwaitleaks the child. Kill it if it is still doing something (it may be holding a socket nothing will read), andwaitit either way so it isn't left a zombie under whatever this process execs into.
Concurrency and shared state (PR #38)
- Fixed-name temp files, caches, or locks that two concurrent runs can collide on (pall8t runs in parallel panes by design). Per-pid names + atomic rename; define what the second writer publishing means.
- State shared across a mount/process boundary: who can mutate it between your check and your use?
Claims vs code (PR #38)
- Do ADR/README/skill statements match what the code does in the degraded paths — missing optional dependency, failed setup, mode switched off? Docs written before the code hardened are the usual drift site. Read the doc diff against the code diff, not against memory.
- Preconditions stated as absolutes ("X works inside the sandbox") that are actually conditional — qualify them.
- What a dependency pulls in (PR #111): a comment saying which
crates a feature selection avoids is a claim about the feature table,
not about the flag. proptest's
stditself enablesregex-syntax, sodefault-features = falsedid not drop the regex engine the comment said it did. Read the dependency's[features]and confirm withcargo tree -i <crate>— without narrowing-e:-e devshows only dev edges, and a crate reached through the dev-dependency's own normal edge then prints "nothing to print", which reads as "not pulled in".
CI workflows (PR #39)
actions/checkout:persist-credentials: falseunless the job pushes.- Event triggers: does the trigger set cover the loop, not just the
first pass (e.g.
synchronizefor re-reviews)? If a trigger is omitted deliberately (cost), say so inline or it reads as a bug. - Listing APIs (
gh api):--paginateor the first page silently truncates. - Report-only jobs:
continue-on-errorwhere a report must not gate.
Impact beyond the diff (standing — use the LSP tool)
- For every public function, type, or constant whose signature, contract,
or semantics the diff changes: enumerate ALL call/use sites with the
LSP tool (
incomingCallsfor functions,findReferencesotherwise) — not grep, which misses renames, method syntax, and re-exports. Then check each site the diff does not touch: does it still hold under the new behavior? An updated callee with an unexamined caller is a finding. - Changed enum/match-heavy types:
findReferenceson the type, looking for match sites that a new variant or changed default now reaches. - Position gotcha:
documentSymbolreports a symbol's range including its doc comment; position-based operations (hover,incomingCalls,findReferences) need the line/character of the identifier itself, so read the declaration line first. If the LSP server is unavailable (e.g. it needs a session restart after a crash loop), say so in the review output and fall back torg— silently degraded coverage reads as full coverage.
What the commit actually contains (PR #46)
git status --shortis step 0 for a reason: read the staged file list before committing, not just the diff you meant to write.git add -Aafter running a tool sweeps in whatever that tool wrote —cargo mutantsleavesmutants.out/andmutants.out.old/, andmutants.out/lock.jsoncarries the developer's hostname and username. An incidental local output like that belongs in.gitignorebefore it belongs in a commit — which is not the same as "never commit generated files": plenty of repos version lockfiles, schemas, or generated sources on purpose, and those stay in review like any other code. The question is whether the file is a deliberate artifact of the project or a byproduct of the tool you happened to run. On an unmerged branch, amend rather than adding a removal commit — a "remove the artifact" commit still merges the artifact's contents intomain's history forever.- A committed report also attracts review findings about its own
contents (bots read
missed.txtas if it were source), which buries the real findings.
Changing a default (PR #46)
- A default change is not one behavior change, it is one per input shape
the old default used to handle. Enumerate them: which layouts, formats,
or states did the old path absorb that the new one meets directly?
Read-only mounts broke linked git worktrees as reference repos —
their
.gitis a pointer file to a path outside the source — precisely because the old path laundered them throughgit clone --localand the new one does not. - A new mechanism may not inherit the properties of the one it replaces. Check identity, permissions, and ownership across the boundary, not just the behavior you were aiming at: apple/container applies its uid/gid remapping to writable mounts only, so read-only mounts arrive root-owned and git refuses them — the feature "worked" while being useless for its main purpose.
- Verify the new default on the real runtime with the tool the users use
(
git, notcat). A read check that only opens a file will not notice that every VCS operation fails.
Lifecycle claims in docs (PR #46)
- Before writing what happens to something "at the end of the run" —
discarded, cleaned up, disposable, temporary — find the code that
removes it. If there is no such code, it persists. The clone under
~/.pall8t/reposwas called disposable in four documents whileprepare's own doc comment two lines away said an existing one is reused as-is.
Where a doc insert landed (PR #68)
- CHANGELOG entries are appended under a heading, and the heading the diff
found may not be the one you meant:
## [Unreleased]here has no### Fixed, so a fix entry drifts down to the nearest one — which belongs to an already-released version. Nothing catches it: the file parses, CI's release-notes guard only checks the current version's heading exists, and the entry then never appears in the next release's notes while retroactively claiming a shipped version contained the fix. Read the section header above an inserted entry, not just the diff hunk. - Same question for any append into a structured doc (ADR lists, tables,
a README section):
grep -n "^## "and check which section the new line actually sits in.
Test fixtures that shell out (PR #68)
- A fixture that isolates the host's config is not isolated from the
host's environment.
GIT_DIRoutranksgit -C <fixture>, and every git hook,git rebase --execandgit bisect runexports it — socargo testlaunched from any of those runs the fixture against the surrounding repository:git initre-initializes the outer repo, the fixture gets no.git, and the fixture's commit lands in the developer's history. Clear the whole channel (GIT_DIR,GIT_WORK_TREE,GIT_INDEX_FILE,GIT_COMMON_DIR), not the one variable that bit you. - Pin it on the built command rather than by exporting the variable around a live run — the suite is multi-threaded and the environment is process-wide. And spell the expected list out in the test: a test that iterates the same constant the code does checks one thing fewer when an entry is deleted, and stays green.
Inserting an item next to an existing one (PR #94, #105)
- Anchoring an insertion on
#[test],fn name(, or any line that is part of an item rather than its first line lands the new text between that item's attributes/doc comment and the item itself. Two symptoms, and only one of them is loud:- an orphaned
#[test]leaves the old test silently not running. Caught here by-D warnings(the function becomes dead code) — but only because nothing else referenced it. - a split doc comment silently documents the wrong item: it compiles, every test passes, and the item that lost its explanation is the one a reader reaches for. Nothing in the toolchain catches this; an external reviewer did.
- an orphaned
- Anchor on the whole item instead — the doc comment's first line, or the
blank line before it — and after inserting into a test module, check
the count rather than the output:
cargo test --quiet -- --list | grep -c ': test$'must rise by exactly the number of tests added. A test that stopped being a test shows up there and nowhere else. - This repo writes
/// docabove#[test], which is also the order that makes a stray insertion visible rather than merely wrong.
Property-test generators (PR #111)
- A generator that holds a dimension constant puts the code reading that
dimension out of the property's reach, and the property still passes:
a server identity whose device and birth time never varied passed an
identity check reduced to the inode alone, and a clock counted up per
step (
1, 2, 3, …) left the session being written always the newest, so an evictor without its "never the entry just written" filter agreed with the model on every generated sequence. - For each field the code under test compares, and each order it derives from the sequence, ask what the generator would have to emit to tell the real rule from the plausible wrong one — then make that wrong rule by hand and watch the property go red. Green against a hand-broken rule is a generator finding, not a passing test.
An assertion that forbids a string (PR #117)
assert!(!msg.contains(X))forbids X everywhere in the output, which is almost always wider than the claim being made — and the extra width is invisible until something legitimate says X. The host's home must not appear as the expanded target; asserting it appears nowhere also forbade the message's owne.g. /home/dev/notes, and the test then failed on the advice rather than on a bug, in every environment where$HOMEis/home/dev(which is every pall8t sandbox).- Name the exact string that would mean the bug, build it from the test's own input, and pick an input nothing else in the message can spell. Then ask the other direction too: would this assertion fail on a message that is right? A proxy that can is a flake with a date on it.
Tests (standing)
- Per docs/testing.md: new tests use table form with reasoned assertion messages; each bug fix and each refuted review finding gets a pin; contracts (argv shapes, wire formats, exit codes) are asserted structurally.
2. Fix, don't file
This is a pre-PR review: findings are yours to fix now, in the same branch, each with its pinning test where applicable. Re-run the gates and re-pass the lenses over what changed. Declining a lens's advice is fine — but then the code or doc must carry the rationale, because the external reviewers will raise it otherwise and the PR reply will just repeat what should have been written down.
3. Grow the lenses
When an external reviewer (bot or human) later finds something real that this review missed, don't just fix it — generalize it into a lens above (or sharpen an existing one) with the source PR noted, in the same PR that fixes the finding. That's the ratchet: each external catch should be a category caught locally forever after. Findings that were refuted don't become lenses; they become clearer code (see the review-loop skill).
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
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.

