agentleFS
TakiTakeTakiTake/pall8t/.claude/skills/local-review/SKILL.md

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

  • Other versions7 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 7

    1. windmill-labs/windmill★ 19ksame name
    2. lablup/backend.ai★ 681same name
    3. oracle/mcp★ 483same name
    4. Pubx-ai/skills★ 6same name
    5. fedemelo/agent-config★ 4same name
    6. khou/skills★ 1same name
    7. 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.

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
  1. Distinctive:

    Every finding a bot catches after push is one this review should have caught before it.

    line 9
  2. Distinctive:

    Before reading anything, run the machine's share — style and lint findings are its job, not this review's:

    line 21
  3. Distinctive:

    Read the full diff once for orientation, then pass through the lenses below.

    line 34
  4. Very specific:

    A deprecation/ignored-setting warning is itself user intent: check which commands reach the print.

    line 67
  5. Very specific:

    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 …

    line 126
  6. Very specific:

    Read the consumer's parser before deciding what is safe (split(":"), maxSplits, whether extra fields error or are silently accepted).

    line 168
  7. Very specific:

    Do ADR/README/skill statements match what the code does *in the degraded paths* — missing optional dependency, failed setup, mode switched …

    line 195
  8. Very specific:

    Read-only mounts broke *linked git worktrees* as reference repos — their .git is a pointer file to a path outside the source — precisely …

    line 260
  9. Distinctive:

    Check identity, permissions, and ownership across the boundary, not just the behavior you were aiming at: apple/container applies its …

    line 265
  10. Very specific:

    Verify the new default on the real runtime with the tool the users use (git, not cat).

    line 270
  11. Distinctive:

    Before writing what happens to something "at the end of the run" — discarded, cleaned up, disposable, temporary — find the code that …

    line 275
  12. Distinctive:

    Read the section header above an inserted entry, not just the diff hunk.

    line 290
  13. Distinctive:

    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 …

    line 377

“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.

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

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 too

Review 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 test

For 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 with as_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.toml over 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, and project.or(global) is the wrong merge for it — [container] ssh = true in 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 under set -e that 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. candidates yielded name plus 2..=N (N names); the retry loop ran for counter in 2..=N around 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: ECONNREFUSED and "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 was SIGKILLed (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, not sock_exists — and the gap gets hard to write down: connect(2) separates listening from dead node from unlinked, where one exists() 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,y for 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 $HOME turns a two-field -v host:guest into 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.sock should not chmod /tmp to 0700 on its way to failing.
  • Spawned children on error paths: a bail! between spawn and wait leaks the child. Kill it if it is still doing something (it may be holding a socket nothing will read), and wait it 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 std itself enables regex-syntax, so default-features = false did not drop the regex engine the comment said it did. Read the dependency's [features] and confirm with cargo tree -i <crate> — without narrowing -e: -e dev shows 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: false unless the job pushes.
  • Event triggers: does the trigger set cover the loop, not just the first pass (e.g. synchronize for re-reviews)? If a trigger is omitted deliberately (cost), say so inline or it reads as a bug.
  • Listing APIs (gh api): --paginate or the first page silently truncates.
  • Report-only jobs: continue-on-error where 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 (incomingCalls for functions, findReferences otherwise) — 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: findReferences on the type, looking for match sites that a new variant or changed default now reaches.
  • Position gotcha: documentSymbol reports 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 to rg — silently degraded coverage reads as full coverage.

What the commit actually contains (PR #46)

  • git status --short is step 0 for a reason: read the staged file list before committing, not just the diff you meant to write. git add -A after running a tool sweeps in whatever that tool wrote — cargo mutants leaves mutants.out/ and mutants.out.old/, and mutants.out/lock.json carries the developer's hostname and username. An incidental local output like that belongs in .gitignore before 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 into main's history forever.
  • A committed report also attracts review findings about its own contents (bots read missed.txt as 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 .git is a pointer file to a path outside the source — precisely because the old path laundered them through git clone --local and 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, not cat). 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/repos was called disposable in four documents while prepare'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_DIR outranks git -C <fixture>, and every git hook, git rebase --exec and git bisect run exports it — so cargo test launched from any of those runs the fixture against the surrounding repository: git init re-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.
  • 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 /// doc above #[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 own e.g. /home/dev/notes, and the test then failed on the advice rather than on a bug, in every environment where $HOME is /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).

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.