Lekker Review
FAANG-grade code review. Isolated worktree checkout, full context gathering (issue tracker + chat + docs + framework docs + monitoring + CI, whichever you have MCP tools configured for), then 5 parallel specialized review agents, a finding-verification pass, and one unified markdown output.
An optional --engine revmux flag can replace the Step 2 native pipeline with
revmux (profiles and lenses under references/revmux/). The default engine is
workflow in Claude Code and codex in OpenAI Codex. All engines feed the same
Step 3 synthesis and finding schema.
Two modes, same review engine:
| Mode | Target | Entry |
|---|---|---|
| pr | An open GitHub PR | a PR url / repo N / repo "title" |
| branch | A local branch, before it is pushed | branch [ref], or --branch |
Branch mode exists to move the review left: everything a bot reviewer
(Greptile, CodeRabbit, or similar) would charge for on the PR is found and
FIXED locally first, so the PR opens clean and there is little left to bill
for. It reviews the same diff a PR would show - merge-base against the branch
the PR would target - and it defaults to --fix.
Each finding contains: file + risk · bad code verbatim · why it's
wrong · fix with code example - ready to paste directly into GitHub.
Reviews are saved to ~/code-reviews/ for future reference.
Optionally the skill then applies its own findings (--fix): fix agents edit
the worktree, a read-only verifier checks each edit against the real git diff,
static checks run, one commit lands per file, and nothing is pushed until the
user says so. Procedure in references/fix-mode.md.
No nitpicking. Critical and Important findings are reserved for things that could cause bugs, outages, data loss, security incidents, or real performance problems at scale.
Boundary-first review rule: for stateful or integration-heavy changes, review the complete behavioral chain rather than the changed helper alone:
production entry point
→ decision point
→ runtime realization
→ downstream consumer
→ persistence/cache/cleanup owner
Require the review to distinguish logical identity from physical/runtime
identity, and to test the relevant transition matrix: success, null, undefined,
exception, retry, fallback, rotation, cache reuse/eviction, proxy parity, and
quoted/history input where applicable. A copied helper test is isolated
evidence, not proof that the production boundary works.
Every verdict-affecting finding should carry a boundary map and an evidence class. The report must distinguish source inspection, isolated tests, repository tests, composed production-entry probes, production probes, and hosted CI. Never upgrade one evidence class into another in the wording.
After a fix, re-run the original proof and audit the newly changed lifecycle boundary for regressions. A green reproduction is necessary, not sufficient.
HARD RULE: the ## 💰 Review Cost block is mandatory. Every review MUST
end with an evidence-backed cost block and no <N> placeholders. Use real
numbers for measurements the host exposes; follow references/output-format.md
for Codex fields the host does not expose. A review without the block is
incomplete.
Set up before first use
This skill ships with no hard rules of its own: references/house-rules.md
is a template. Fill it in with your team's own non-negotiable conventions
(type safety, pagination, PR-title format, repo-placement taxonomy, stack
context) before relying on the Critical-severity hard-rule gate. Until then,
the 5 specialist agents still run and still find real bugs. They just don't
have a codified "always Critical" rule list to check against.
If any hard rule you define carries a rule tag (e.g. "TS-1"), reviewer
agents attach that tag to matching findings. The verifier checks the diff
anchor and rule applicability, but skips its five runtime-failure challenges.
Those challenges cannot evaluate a standards violation. A tagged finding keeps
Critical severity only when both rule-specific checks pass. The workflow
returns the number checked as hardRuleCount.
SKILL_ROOT means this skill's installed directory. In Claude Code it is
${CLAUDE_PLUGIN_ROOT}. In Codex, derive it from the selected SKILL.md path.
Resolve every references/... and script path relative to SKILL_ROOT; never
assume a ~/.claude/skills/ installation path.
Run one simple command per shell call. Do not prefix commands with
cd <dir> &&; use absolute paths, git -C <dir>, and grep -rn <pattern> <dir>
instead. Permission checkers cannot vet a compound or cd-prefixed command,
so in an unattended or auto-approved run each one becomes a denial and a
wasted turn.
Host selection
Set HOST=codex when native Codex collaboration tools such as spawn_agent
and wait_agent are available. Otherwise set HOST=claude when Workflow and
Agent are available. If neither orchestration surface exists, stop: a
single-agent review is not equivalent to lekker-review.
HOST=claude: useworkflow.jsandfix-workflow.jsas documented below.HOST=codex: read and followreferences/codex-workflow.md; it is the authoritative Codex native collaboration contract for review and fix mode.ENGINE=revmux: use the same external engine from either host. Revmux itself decides which configured runners are supported; lekker-review does not reject a runner merely because its profile name containscodex/.
Step 0 - Parse input
Dependencies (first thing, every run)
node ${SKILL_ROOT}/scripts/deps.mjs check # add --unattended when no human is present
Milliseconds: it only checks presence. The upstream version check needs the
network, so it runs at most once per cadenceDays (default 7) and the ledger
~/.local/state/lekker-review/deps.json records when it last ran. Act on state:
first-run: ask ONCE (AskUserQuestion in Claude Code): a multiSelect of theoffer[]tools (label = tool, description =usedBy), plus "keep them updated automatically?" yes/no. Thendeps.mjs init --install <picked> --skip <the rest> --auto-update on|off. A tool not picked is recorded as skipped and never offered again; the user can still rundeps.mjs install <tool>later. Unattended: do not ask, do not install; carry on and saydeps not initialisedin the header.missing-required: stop and print themissinglist. The review needs them.undecidednon-empty (a tool added to the registry since init): ask about those tools only, thendeps.mjs install <tool>ordeps.mjs skip <tool>.outdatednon-empty andupdatednull: one line, e.g.deps outdated: revmux 0.2.6 -> 0.2.7 (deps.mjs update). With auto-update on,checkalready upgraded them when the check was due; reportupdated.revmuxPromptsInSync: false: runbash ${SKILL_ROOT}/scripts/install-revmux-prompts.sh, which resyncs the lekker profiles into~/.config/revmux(deps.mjs update revmuxdoes the same after upgrading).- An install that returns
manual(no Homebrew on PATH) prints the command to run by hand; pass it on, do not improvise another installer.
ENGINE=revmux additionally needs revmux present; when it is missing or
skipped, fall back to the host's native engine and say why in the header.
Pick the mode first
MODE=branch when ANY of these hold:
- the argument is the literal word
branch(optionally followed by a ref), or the flag--branch [ref]is present - the user asked for a review "before push", "before the PR", "of my branch", "of these commits", or named a local branch that has no open PR
- no PR reference was given at all and
$PWDis inside a git repo on a branch that is not the base branch
Otherwise MODE=pr.
Never guess between the two. If a PR reference is present, it is pr mode
even in a git repo. If neither a PR reference nor a git repo is available,
stop and ask - do not review the wrong thing.
MODE=pr
Accept any of:
- Full GitHub URL:
https://github.com/owner/repo/pull/123 - Repo + number:
my-service 42 - Repo + partial title:
my-service "add offline orders"
If the user gives a short repo name without an org/owner, ask once which
org/owner it belongs to (or use a default you've configured), then build
REPO_SLUG as <owner>/<name>.
Derive and carry these variables through every subsequent step:
REPO_SLUG(e.g.my-org/my-service)PR_NUMBERPR_BRANCH(fromgh pr view)PR_URL=https://github.com/<REPO_SLUG>/pull/<PR_NUMBER>TARGET_LABEL=PR #<PR_NUMBER>
MODE=branch
Resolve everything from the local repo - no gh pr call, no network:
LOCAL_REPO=$(git -C "$PWD" rev-parse --show-toplevel)
# Use the ref the user named when present. Otherwise require an attached branch.
LOCAL_BRANCH="${USER_PROVIDED_REF:-}"
if [ -z "$LOCAL_BRANCH" ]; then
LOCAL_BRANCH=$(git -C "$LOCAL_REPO" symbolic-ref --short -q HEAD)
fi
if [ -z "$LOCAL_BRANCH" ]; then
echo "Detached HEAD: name the local ref to review." >&2
exit 1
fi
ORIGIN_URL=$(git -C "$LOCAL_REPO" remote get-url origin 2>/dev/null || true)
if [ -n "$ORIGIN_URL" ]; then
REPO_SLUG=$(printf '%s\n' "$ORIGIN_URL" \
| sed -E 's#(git@github.com:|https://github.com/)##; s#\.git$##')
else
LOCAL_REPO_NAME=$(basename "$LOCAL_REPO" \
| sed -E 's#[^[:alnum:]_.-]+#-#g; s#^-+|-+$##g')
REPO_SLUG="local/${LOCAL_REPO_NAME:-repository}"
fi
An explicitly named ref may be reviewed from detached HEAD. Before landing
fixes, resolve it to a local branch name or stop; never build
refs/heads/<LOCAL_BRANCH> from a commit SHA or another non-branch ref. The
local/<directory> slug is reporting metadata for repositories without an
origin; preserve the origin-derived slug whenever that remote exists.
Then:
BASE_REF: the branch the PR would target. Honour--base <ref>when given. Otherwise letscripts/changed-files.shdetect it (origin's default branch, then whatever your convention falls back to) and report which one it picked. If detection lands on something that contradicts your team's actual convention, say so in the review header rather than reviewing silently against the wrong base.PR_NUMBER= null,PR_URL= null,TARGET_LABEL=branch <LOCAL_BRANCH>.- The reviewed diff is
merge-base(HEAD, BASE_REF)..HEAD- committed work only. Uncommitted and untracked changes are NOT reviewed. Ifgit status --porcelainis non-empty, say so in one line before starting (⚠️ N uncommitted file(s) are not part of this review) so nobody assumes coverage that does not exist. - If that diff is empty, stop:
nothing to review - <branch> matches <base>.
Guard: never run branch mode on a long-lived integration branch. If
LOCAL_BRANCH is main, master, develop, staging, or production, stop
and say so.
Depth: record an explicit scan, medium, deep or deps request;
otherwise select a provisional depth from the per-file stats. In pr mode use
gh pr view <PR_NUMBER> --repo <REPO_SLUG> --json additions,deletions,changedFiles,files,baseRefName,state,mergeCommit.
Keep baseRefName as BASE_BRANCH, changedFiles as EXPECTED_FILES, and
mergeCommit.oid as MERGE_COMMIT when merged. In branch mode use
git diff --numstat <MERGE_BASE> HEAD.
Mandatory risk check (every depth, including explicit requests): after
Track B has saved pr.diff, and before finalizing depth or starting Step 2,
run scripts/risk-paths.mjs with that diff and the exact changed paths.
Resolve the script beside the selected SKILL.md: in Codex use
<directory containing selected SKILL.md>/scripts/risk-paths.mjs; in Claude
use ${CLAUDE_PLUGIN_ROOT}/skills/lekker-review/scripts/risk-paths.mjs.
Use a shell-free process API with separate arguments:
execFileSync('node', [riskScript, '--diff', diffFile, '--', ...changedPaths]).
Never interpolate PR-controlled paths into shell source. Alternatively pipe
git diff --name-only -z <MERGE_BASE> HEAD into
node "<resolved riskScript>" --stdin0 --diff "<scratchpad>/pr.diff".
Do not continue on classifier failure; report risk classification unavailable.
The classifier detects configured path patterns for CI workflows, auth,
billing, installers/setup, and P21, plus p21 in added lines. These are path
heuristics, not complete detection of auth/billing behavior in generic files;
reviewers still inspect that behavior in the diff. Whenever
needsHumanReview: true, always put NEEDS HUMAN REVIEW: <categories> in the
review header, even for an explicit scan. A human must read those paths.
Explicit depth wins, but never suppresses this marker. Without an explicit request, apply AUTO-DEPTH in this order after the risk check:
deepif the classifier returnsdeep: true, additions+deletions > 800, changedFiles > 25, or the diff touchesmigrations/or*.sql.deps(candidate) if every changed file is a lockfile orpackage.json. Confirm after Track A withscripts/deps-only.mjs; until then run Track B as forscan.scanif additions+deletions < 150 AND changedFiles <= 5.mediumotherwise.
Lockfiles (package-lock.json, npm-shrinkwrap.json, yarn.lock,
pnpm-lock.yaml, bun.lock, bun.lockb) do not count toward additions+deletions.
Step 0 depth is provisional: if the mandatory check upgrades scan, run Track A
and gather the newly required Track B sources before Step 2. Branch mode uses
Track A's merge-base diff. State final depth and whether auto-selected in the
review header.
--post flag: parse and store as POST_REVIEW=true.
--fix flag: parse and store as FIX_MODE=true. Fix mode needs a real
checkout, so --fix forces Track A (worktree setup) to run even when
depth=scan. If the user did NOT pass --fix, leave FIX_MODE=false for now -
Step 4 offers it after the review is printed.
Branch mode defaults to fix. In MODE=branch, FIX_MODE=true and
FIX_SCOPE=critical+important unless the user passed --no-fix. That is the
whole point of reviewing pre-push: findings get applied before the PR exists,
so a bot reviewer never sees them. Landing those fixes on the local branch
still needs explicit confirmation (Step 4).
--base <ref> flag (branch mode only): overrides base-ref detection. Passed
through to the scripts as LEKKER_BASE_REF. Ignored in pr mode, where the
base comes from the PR: Track A passes LEKKER_BASE_REF=origin/<BASE_BRANCH>
itself, so the script fetches the base and diffs against its current tip.
--no-fix flag: parse and store as FIX_MODE=false, and do not offer fixes
in Step 4. Use it for a read-only pre-push look.
--no-artifact flag: parse and store as ARTIFACT=false (default true).
Skips Step 3.5 (living review artifact) silently.
--no-fun flag: parse and store as FUN=false (default true). Skips the
closer (Step 3) everywhere: terminal, saved file, artifact, GitHub body.
--engine revmux|workflow|codex flag: parse and store as ENGINE. Default
to workflow for HOST=claude and codex for HOST=codex. Reject an explicit
engine that does not exist on the current host (workflow requires Claude's
Workflow tool; codex requires Codex native collaboration). revmux is
allowed only at depth medium or deep - revmux's
scripts reject scan (see Depth gate). If depth resolves to scan or deps
(explicit or auto), force ENGINE back to the current host's native engine regardless of
the flag and note engine forced to <workflow|codex> - revmux needs medium/deep in the review header.
--deterministic-dedup flag: after resolving ENGINE, opt in to the trusted
native dedup helper for the initial Review -> Dedup stage only. Record it as
deterministicDedup in CONTEXT_FILE. Accept it only with ENGINE=codex;
otherwise report unsupported and stop. Without the flag, preserve the existing
manual native merge.
Re-review detection: run
ls ~/code-reviews/*-<TARGET_SLUG>-<repo-short-name>.md 2>/dev/null | sort | tail -1
(TARGET_SLUG = pr-<PR_NUMBER> in pr mode, branch-<LOCAL_BRANCH sanitized to [a-z0-9-]> in branch mode)
to find the newest prior review for this PR (repo-short-name = last segment of
REPO_SLUG; keeps PR numbers from colliding across repos). If found, grep it for
\*\*Head:\*\* and extract the short sha. Set PREV_SHA=<sha> and
PREV_REVIEW_FILE=<path>. If no Head line exists in the file (older format),
treat as a full review and leave PREV_SHA unset. Also grep the same file for
\*\*Artifact:\*\* and set PREV_ARTIFACT_TARGET=<target> (null when absent)
- Step 3.5 reuses that exact URL or local path so the artifact stays a living page for this PR.
Convergence state (every PR, first review included): the review file
records only the last head sha, so finding status lives in
scripts/finding-state.mjs (one JSON file per PR under
~/.local/state/lekker-review/findings/). In pr mode, on a re-review, first
fetch the PR's review threads into <scratchpad>/threads.json as
{ "prAuthor": <login>, "threads": [{ path, line, body, isResolved, isOutdated, replies: [{ author, body }] }] } (gh api graphql over reviewThreads; body
is the first comment, replies the later ones). Then run
node "${CLAUDE_PLUGIN_ROOT}/skills/lekker-review/scripts/finding-state.mjs" begin --repo <REPO_SLUG> --target <TARGET_SLUG> --run <RUN_ID> [--threads <scratchpad>/threads.json].
RUN_ID is one id per review attempt, saved to <scratchpad>/finding-run-id
and reused when that attempt is retried, so a retry does not count as a new
cycle. In Codex, replace the quoted script path with the absolute path to
scripts/finding-state.mjs beside the selected SKILL.md, as for run-log. Pass
its cycle, suppressed and recurringClasses to the workflow. A
finding is fixed when its thread is outdated, intentional when the author
replied "by design" and nothing changed, rejected when the author dismissed it
or the thread was resolved with no code change. The workflow never re-raises a
suppressed (rejected or intentional) finding. From cycle 4 the workflow
returns verdict: "rethink" with the recurring finding classes and runs no
agents: skip Steps 2 to 4, render the verdict as RETHINK THE APPROACH: this PR has been reviewed N times; the same classes keep coming back: <classes>, and
suggest the author and reviewer agree the approach before another round.
Run finding-state.mjs record --run <RUN_ID> --repo ... --target ... --findings <findings.json>
before the review is published or the artifact is updated, so a stop after
publishing cannot lose what was raised. --run files the findings under this
attempt's cycle even when another review of the PR started in the meantime.
Open the run log once mode, depth and engine are settled (see
references/traces.md for where every trace of a run lives):
Resolve the run-log script path in every shell call. The examples below use
Claude Code's CLAUDE_PLUGIN_ROOT. In Codex, replace the quoted script path in
each invocation with the absolute path to scripts/run-log.mjs beside the
selected SKILL.md. Do not rely on a shell variable set by an earlier call.
node "${CLAUDE_PLUGIN_ROOT}/skills/lekker-review/scripts/run-log.mjs" start --repo <REPO_SLUG> --target <TARGET_SLUG> --mode <MODE> \
--depth <depth> --engine <ENGINE> [--fix]
Keep the returned runId as RUN_ID. Then run
node "${CLAUDE_PLUGIN_ROOT}/skills/lekker-review/scripts/run-log.mjs" mark <RUN_ID> <phase>
at each step boundary: context (Step 1), review (Step 2), synthesis
(Step 3), fix (Step 4), post (Step 5). A marker is one line of JSON; never
skip the review because the log failed, just say run log unavailable.
Depth gate
| Step | 📦 deps | scan | medium | deep |
|---|---|---|---|---|
| Context: issue-tracker/CI/diff/existing-reviews | always | always | always | always |
| Context: chat/docs/framework-docs/monitoring/prior-review-memory (optional, MCP-dependent) | skip | skip | included | included + broader recall |
| Worktree + static checks | included (npm ci per changed lockfile) |
skip (WORKTREE_PATH=null) unless --fix |
included | included |
| Review agents | 1 deps checklist | 2 triage (haiku) + project-rules (sonnet) | 5 specialists + project-rules (sonnet) | 5 specialists + project-rules (sonnet) |
| Per-finding verification | none | Criticals + Importants | Criticals + Importants | Criticals + Importants |
| Completeness critic | skip | skip | skip | included |
| Proof-of-bug (failing test per Critical or composed-boundary Important) | skip | skip | included (max 5) | included (max 5) |
| Living review artifact | included | included | included | included |
| Housekeeping (optional memory/notes writeback) | skip | skip | included | included |
--post |
supported | supported | supported | supported |
--fix / fix offer |
supported | supported (forces worktree) | supported | supported |
For scan: note ⚡ scan - worktree unavailable, static checks skipped in the
review header. When --fix forced the worktree at scan depth, drop that note
and say ⚡ scan - worktree created for --fix instead.
Branch mode always has a worktree (fix mode is the default, and there is no remote diff to fall back on), so the scan row's "skip worktree" never applies. Everything else in the table is unchanged: branch mode is not a shallower review, it is the same review earlier. Two rows differ because their inputs do not exist yet:
| Step | branch mode |
|---|---|
| CI checks | N/A - not pushed; local compiler/linter/tests are the only signal |
| Existing bot reviews | none by definition - that is the saving |
--post |
unsupported until a PR exists (Step 4.6 can create one) |
Step 1 - Context + worktree (concurrent)
Fire both tracks in the same turn.
Track A - worktree setup (skip when depth=scan, unless --fix)
At scan depth, collect review guidance without creating a worktree:
LEKKER_RULES_ONLY=1 LEKKER_BASE_REF=origin/<BASE_BRANCH> \
${SKILL_ROOT}/scripts/setup-worktree.sh \
<REPO_SLUG> <PR_BRANCH> <scratchpad>/rules.json
Read projectRules from rules.json into context.json. This archive-only
mode fetches the PR base and reads baseProjectRules at the merge base with the PR branch (as full mode does), not at the base tip. If the base cannot be fetched, resolved or merge-based, baseProjectRules is null and notes carries base-rules-unavailable; the scan still succeeds. It does not run static checks.
Run via Bash with run_in_background:
# MODE=pr - fetches origin/<PR_BRANCH> AND origin/<BASE_BRANCH>, then checks out
# the PR branch. Without the base fetch the merge-base is whatever this clone
# last saw, and the file list widens (65 files instead of 9 on one PR).
# LEKKER_EXPECTED_FILES lets the script report a list that still disagrees.
LEKKER_BASE_REF=origin/<BASE_BRANCH> LEKKER_EXPECTED_FILES=<EXPECTED_FILES> \
${SKILL_ROOT}/scripts/setup-worktree.sh \
<REPO_SLUG> <PR_BRANCH> <scratchpad>/worktree.json [PREV_SHA]
# MODE=pr, PR already MERGED - the head is inside the base branch now, so
# merge-base(head, origin/<BASE_BRANCH>) is the head and the diff is empty.
# Diff against the base as it was just before the merge instead.
LEKKER_BASE_BRANCH=<BASE_BRANCH> LEKKER_BASE_REF=<MERGE_COMMIT>^1 \
LEKKER_EXPECTED_FILES=<EXPECTED_FILES> \
${SKILL_ROOT}/scripts/setup-worktree.sh \
<REPO_SLUG> <PR_BRANCH> <scratchpad>/worktree.json [PREV_SHA]
# MODE=branch - LOCAL ref only. LEKKER_LOCAL_REPO skips repo discovery, the
# fetch, and the origin/<branch> checkout entirely, and creates the worktree
# DETACHED so a branch already checked out in the user's own working copy can
# still be reviewed. LEKKER_BASE_REF is set only when --base was given.
LEKKER_LOCAL_REPO=<LOCAL_REPO> [LEKKER_BASE_REF=<BASE_REF>] \
${SKILL_ROOT}/scripts/setup-worktree.sh \
<REPO_SLUG> <LOCAL_BRANCH> <scratchpad>/worktree.json [PREV_SHA]
On completion, read worktree.json. Keys emitted:
worktreePath, repoRoot, headSha, headShaShort, tscTail,
tscChangedTail, tscErrorCount, eslintTail, eslintScope, eslintJson,
eslintProvenance, changedFiles, baseRef, mergeBase, projectRules, deltaFile, notes,
depsInstall, testRunner.
eslintProvenance is the provenance-only receipt for eslintJson (base/head, tracked-worktree state, exit code, raw report hash).
testRunner is {runner, dirs, reason} from scripts/test-runner.mjs:
runner is vitest|jest|mocha|node-test only when its binary is installed
in the worktree, dirs lists {dir, runner} pairs for each usable package
(including binaries installed in a parent dir within the worktree), and reason
says why runner is null. Pass it to the workflow unchanged; Prove skips
without one instead of paying provers to find the missing node_modules.
notes containing changed-files-mismatch:<got>-vs-<expected> means the
merge-base still disagrees with the PR. Use the files list from gh pr view
as the changed-file list for the review header and agents, and say so in the
header; the static-check scoping is the script's best effort.
depsInstall is non-empty when the diff changed a lockfile: one row per
lockfile dir, {dir, status: ok|failed|timeout, tail?}. The script ran
npm ci --ignore-scripts there instead of symlinking the repo's
node_modules, which holds the pre-PR dependency tree. A row that is not ok
is evidence for the review (a lockfile npm ci rejects fails the deploy too),
not a reason to stop. Set LEKKER_NO_INSTALL=1 to skip the install. Lockfile
dirs using yarn, pnpm or bun are not installed (note deps-install-unsupported).
Confirm deps depth (only when Step 0 picked the deps candidate):
node ${SKILL_ROOT}/scripts/deps-only.mjs \
<worktreePath> <mergeBase> <changedFiles...> > <scratchpad>/deps-report.json
kind: "deps" confirms it; pass the report as depsReport in CONTEXT_FILE.
kind: "mixed" (a scripts, name or other non-dependency key changed, or a
package.json was added) means re-apply AUTO-DEPTH without the deps rule, and
fetch the Track B sources the new depth includes before Step 2.
mergeBase is the commit the file list was scoped against. Branch mode
generates its diff from that exact sha (below), so the diff the agents read and
the files the static checks were scoped to can never disagree. notes contains
local-branch-mode; when the local path ran.
Static checks are scoped so you can tell this PR's errors from the repo's standing debt - do not try to infer that from the raw tail:
eslintTailis the result of linting onlychangedFiles(eslintScopesayschanged-files). Everything in it belongs to this PR. WheneslintScopeisfull-fallback, base-ref detection failed and the lint is repo-wide again - in that case treat its contents as unattributed and say so rather than blaming the author.tscTailis the raw repo-wide tail (tsc needs the whole program, so it cannot be scoped).tscChangedTailholds only the errors in files this PR touched - that is the attributable set.tscErrorCountis the repo-wide total; a large count with an emptytscChangedTailmeans pre-existing debt, not a finding.- If your stack doesn't use tsc/eslint, adapt
setup-worktree.sh's static check step to your language's compiler/linter equivalents.
A failing CI build or test = Critical finding input.
Bot-comment pre-emption (runs right after worktree.json lands)
The bot reviewers (Greptile, Gemini, CodeRabbit) bill for a predictable class of comment, and most of that class is either the repo's own eslint config or a pattern they have already raised in this repo many times. Both are knowable before the PR exists, so collect them deterministically instead of asking an agent to guess:
# 1. Lint pre-flight - the repo's linter is the authority for this class.
# Skip when eslintJson is null (scan with no worktree, no eslint config, an
# eslint crash, or the repo-wide fallback, whose contents are standing debt).
LEKKER_WORKTREE_PATH=<worktreePath> \
node ${SKILL_ROOT}/scripts/lint-findings.mjs \
<eslintJson from worktree.json> <scratchpad>/preflight.json --base <mergeBase>
# 2. Bot-comment patterns - refresh only when the mined section for this repo
# is missing or older than 30 days; it is history, it does not change hourly.
# Needs `gh` auth with read access to the repo's PR review comments.
# Age comes from the section's own `<!-- mined: YYYY-MM-DD -->` marker, not
# the file mtime: the file is shared, so mining one repo would otherwise
# mark every other repo's section fresh.
BP="${LEKKER_DATA_DIR:-$HOME/.cache/lekker-review}/bot-patterns.md"
MINED=$(awk -v h="## <REPO_SLUG>" '$0==h{f=1;next} f&&/^## /{exit} f&&/^<!-- mined: /{print $3;exit}' "$BP" 2>/dev/null)
CUTOFF=$(date -v-30d +%F 2>/dev/null || date -d '30 days ago' +%F)
if [[ -z "$MINED" || "$MINED" < "$CUTOFF" ]]; then
${SKILL_ROOT}/scripts/mine-bot-comments.sh <REPO_SLUG>
fi
The mined file lives outside the skill directory on purpose: a plugin update replaces the skill directory and would wipe the history.
Then set, for use in CONTEXT_FILE and Step 3:
PREFLIGHT_FILE=<scratchpad>/preflight.jsonwhen step 1 ran, else null.BOT_PATTERNS_FILE= thebot-patterns.mdpath when it contains a## <REPO_SLUG>section, else null. Never pass a file with no section for this repo: another repo's patterns are noise.
Read preflight.json's summary.status. It is clean (lint ran, nothing to
report), issues, empty-report, not-an-eslint-json-report, or
unreadable: <reason>. Only clean licenses saying the lint is green; every
other non-issues value, and a null eslintJson, means the lint verdict is
UNKNOWN and the review header must say so rather than implying a pass.
These findings do not go through the review agents or the verifier. eslint
already proved them by running, the agents are told (via preflightFile) not to
re-report them, and a verifier asking "does this fail at runtime?" of a lint
rule would drop it. Merge them in at Step 3 instead.
When depth=scan: set WORKTREE_PATH=null without launching the script - unless
FIX_MODE=true, in which case run the script anyway (fix mode cannot edit code
from a diff). In MODE=branch the script always runs, at every depth.
A failing local compiler/linter/test run in branch mode is the direct replacement for the failing-CI signal - treat it exactly the same way. Catching it here is a CI run the PR never has to burn.
Track B - metadata and signals (all calls fired in parallel)
Run ALL of the following in the same message. Full query details are in
references/context-gathering.md - follow it, do not paste it wholesale into
agent contexts.
In MODE=branch, every gh pr * call below is skipped - there is no PR.
Wait for Track A's worktree.json (you need mergeBase), then substitute:
# The diff, from the SAME merge-base the file list was scoped to.
git -C <worktreePath> diff <mergeBase> HEAD > <scratchpad>/pr.diff
# Commit log, for ticket ids and for the PR title the branch would need.
git -C <worktreePath> log --format='%s%n%b' <mergeBase>..HEAD
- The title/ticket-prefix check in branch mode is a PRE-check, not a
violation: scan the commit subjects for your team's ticket pattern, collect
the distinct ids, and set
RECOMMENDED_PREFIX. There is no PR title to be wrong yet, soPR_TITLE_ISSUE=false- report the prefix as the title to use, in the Step 4.6 PR offer. - Ticket ids come from the commit log and the branch name instead of the PR title/body; the issue-tracker lookup below is otherwise identical.
ciStatus=N/A - not pushed.existingReviews= null.- Everything else in Track B (issue tracker, chat, docs, framework docs, monitoring, prior-review memory) runs unchanged, keyed off the ticket ids and the branch name.
MODE=pr calls:
gh pr view <PR_NUMBER> --repo <REPO_SLUG>with fields:number,title,body,author,headRefName,baseRefName,labels,linkedBranches,mergeStateStatus,additions,deletions,changedFiles,isDraft,headRefOid. ExtractheadRefOid(full sha) andheadShaShort(first 7).- Title/ticket-prefix check (if
house-rules.mddefines one): scan commit log for the ticket pattern; setPR_TITLE_ISSUEandRECOMMENDED_PREFIX. gh pr diff <PR_NUMBER> --repo <REPO_SLUG> > <scratchpad>/pr.diff- fetched ONCE; all agents read this file viaDIFF_FILE.gh pr checks <PR_NUMBER> --repo <REPO_SLUG>gh pr reviews <PR_NUMBER> --repo <REPO_SLUG>and review comments- Issue-tracker lookup (Linear/Jira/GitHub Issues MCP, if configured) per
ticket ID found in title/body/branch; collect ACs as numbered list (
acList). - (medium/deep only, optional) Chat search (Slack/Discord MCP, if configured): PR-title keywords and ticket ID.
- (medium/deep only, optional) Docs search (Notion/Confluence/wiki MCP, if configured): feature name or ticket title.
- (medium/deep only, optional, only when relevant) Framework/API docs MCP for the specific framework or third-party API the diff touches.
- (medium/deep only, optional) Monitoring search (Sentry/Rollbar/etc. MCP, if configured) for filenames or service names from the diff.
- (medium/deep only, optional) Prior-review-memory recall, if you maintain such a system: patterns and false positives specific to this repo.
Collect shared deterministic evidence
For a run with worktree.json, collect once through the trusted installed
helper before assembling context. Never run a copy from the reviewed worktree:
node "<SKILL_ROOT>/scripts/evidence-bundle.mjs" \
--worktree "<scratchpad>/worktree.json" > "<scratchpad>/evidence-bundle.json"
jq 'del(.git.diff.text, .lint.report, .boundary.report.results)' "<scratchpad>/evidence-bundle.json" \
> "<scratchpad>/static-evidence.json"
Boundary probes are optional and remain off unless the operator explicitly
opts in with --trusted-boundary-opt-in, --boundary-config, and
--boundary-out. The fixed trusted CLI adapter reads only exact base/head
source from observed Git evidence. Follow
references/boundary-evidence.md for the
local configuration. Include the compact boundary status, provenance, candidate
summary, and verified reduced failure code with its stderr hash/path in semantic review context. Treat candidates as evidence for
review; they never create findings or a clean verdict automatically. If opted
in collection is unavailable, preserve its reason in the bundle.
Check each exit status and re-read the JSON. Missing tools, nonzero exits or malformed output make this collection unavailable: preserve diagnostics and set both context paths below to null. Do not silently pass an empty file. When Git evidence is available, its provenance base/head must match the review's selected commit pair; a mismatch invalidates the collection, never changes the review target. Unavailable Git or lint stays explicitly unknown.
The compact view removes duplicate raw diff text, lint report data, and raw boundary invocation rows, but retains the reduced failure reference after its raw stderr hash is checked. Keep the full bundle for provenance and detail; semantic review still reads DIFF_FILE and existing lint/preflight inputs. Do not replace changedPaths, project rules or the mandatory risk check with a different Git diff. Reuse available pinned inventory instead of recollecting it in every review agent. In scan/no-worktree mode, set both paths to null; do not fabricate a bundle.
Assemble CONTEXT_FILE
Write <scratchpad>/context.json with keys:
{
"acList": "<numbered ACs from your issue tracker, or empty>",
"projectRules": "<worktree.json or rules.json projectRules + any recalled review patterns appended under '## Recalled patterns'>",
"baseProjectRules": "<worktree.json or rules.json baseProjectRules, copied unchanged (no recalled patterns); null when absent>",
"changedPaths": "<PR files[].path list, or an exact matching worktree.json changedFiles list>",
"sentrySignals": "<monitoring issue summaries, or null>",
"ciStatus": "<passing | failing: <names> | pending | N/A>",
"existingReviews": "<prior review summaries>",
"deltaFile": "<worktree.json deltaFile, or null>",
"houseRulesFile": "${SKILL_ROOT}/references/house-rules.md",
"reviewTarget": "<TARGET_LABEL, e.g. 'PR #412' or 'branch feat/offline-orders'>",
"prePush": "<true in MODE=branch, false in MODE=pr>",
"preflightFile": "<PREFLIGHT_FILE, or null>",
"botPatternsFile": "<BOT_PATTERNS_FILE, or null>",
"evidenceBundleFile": "<full evidence-bundle.json path; null on collection failure or no worktree>",
"staticEvidenceFile": "<compact static-evidence.json path; null on collection failure or no worktree>",
"depsReport": "<deps-report.json contents at depth deps, else null>",
"depsInstall": "<worktree.json depsInstall>",
"deterministicDedup": "<boolean: true only for explicit --deterministic-dedup with ENGINE=codex>",
"prBody": "<full PR body at every depth; empty string in branch mode>"
}
prePush: true tells the agents there is no CI verdict and no bot review to
defer to, and that anything they flag is cheaper to fix now than after the PR
opens. It does NOT lower the bar: same severities, same no-nitpicking rule.
Agents read keys from this file. Nothing from CONTEXT_FILE is pasted into their prompts wholesale - the workflow script delivers it by path.
Step 2 - Review engine (review + verify + critic)
ENGINE=codex (OpenAI Codex default)
Read and follow references/codex-workflow.md. Use Codex native collaboration
tools for Review, Dedup, Verify, Critic, Prove, and optional Fix stages. The
coordinator writes <scratchpad>/findings.json using the same result shape as
the Workflow engine, with engine: "codex", then continues at Step 3.
Do not run workflow.js through Node or a shell: it is a Claude Workflow-harness
script with injected globals and a top-level return. Do not replace the native
pipeline with one large subagent; every verdict-affecting finding still needs
an independent adversarial verifier.
ENGINE=workflow (Claude Code default)
First copy the script into the scratchpad. The Workflow tool rejects a
scriptPath outside the working directory or added dirs ("scriptPath must be a
script path this tool returned, or a file you can already read"), and the skill
dir is usually neither: cp ${SKILL_ROOT}/workflow.js <scratchpad>/workflow.js.
If workflow.js is already in the working directory (an unattended runner may
stage it there), use that copy and skip the cp: some permission checks deny
reading fi
…(truncated)
