--- name: lekker-review description: > FAANG-quality PR code review, adaptable to any team. Checks out the branch in an isolated worktree, gathers context from your issue tracker, chat, docs, CI checks, and (optionally) production monitoring, runs 5 parallel specialized review agents (quality/implementation/simplification/conventions/test-quality), verifies every finding against the diff, then outputs a single unified markdown review: file + risk + bad code + why it's wrong + fix, ready to paste directly into GitHub. Saves every review to ~/code-reviews/*.md. Covers business logic, scalability, complexity, data integrity, security, integration contracts, error handling, and migration safety. Critical findings come with PROOF: a prover agent writes a failing test in the worktree demonstrating each bug, and fix mode later re-runs it to show the fix flips it green. Every review also publishes a private living artifact page whose URL stays stable across re-reviews, so the author watches findings close commit by commit. With --fix (or by accepting the post-review offer) it also APPLIES its own Critical/Important findings as real code in the worktree, verifies each edit, commits them, and pushes to the PR branch only after explicit confirmation. Use when the user says "review this PR", "lekker review", "check this PR", "do a code review on PR #N", "review and fix this PR", "apply the review fixes", provides a GitHub PR URL, or asks for a pull request review in any form. license: MIT allowed-tools: Bash, Read, Write, Edit, Agent, Workflow, AskUserQuestion, Artifact compatibility: > Claude Code only. Requires the Workflow tool (multi-agent orchestration) and the Artifact tool (living review page): other Agent Skills-compatible tools without an equivalent to Workflow cannot run the review/verify/critic pipeline this skill depends on. Requires git and gh (GitHub CLI) authenticated. metadata: targets: [_source-only] author: Oleg Koval tags: - code-review - pull-request - github - multi-agent - workflow - quality argument-hint: " [scan|medium|deep] [--post] [--fix]" --- # 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. 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. **HARD RULE: the `## ๐Ÿ’ฐ Review Cost` block is mandatory.** Every review MUST end with a fully-populated cost block (token + price breakdown, real numbers, no `` placeholders). A review without the cost block is incomplete. If you are about to present the review without it, stop and compute it first. --- ## 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 and the workflow **skips adversarial verification** for them. This is deliberate: the verifier's five challenges ask runtime-failure questions ("does this fail on a normal execution?", "can you write the failing test?") that a standards violation can never answer, so verifying them systematically drops the very findings your policy declares non-negotiable. A tagged finding keeps its Critical severity; the workflow returns how many were exempted as `hardRuleCount`, and each carries a `verifierReasoning` saying so. `${CLAUDE_PLUGIN_ROOT}` below refers to this skill's own installed directory: resolve every `references/...` and script path relative to it. --- ## Step 0 - Parse input 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 `/`. Derive and carry these variables through every subsequent step: - `REPO_SLUG` (e.g. `my-org/my-service`) - `PR_NUMBER` - `PR_BRANCH` (from `gh pr view`) - `PR_URL` = `https://github.com//pull/` **Depth:** explicit keyword `scan`, `medium`, or `deep` wins. If absent, run `gh pr view --repo --json additions,deletions,changedFiles` and apply AUTO-DEPTH: - `scan` if additions+deletions < 150 AND changedFiles <= 5 - `deep` if additions+deletions > 800 OR changedFiles > 25 OR diff touches `migrations/` or `*.sql` - `medium` otherwise State the chosen depth (and whether it was 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. **`--no-artifact` flag:** parse and store as `ARTIFACT=false` (default true). Skips Step 3.5 (living review artifact) silently. **Re-review detection:** run `ls ~/code-reviews/*-pr--.md 2>/dev/null | sort | tail -1` 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=` and `PREV_REVIEW_FILE=`. 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_URL=` (null when absent) - Step 3.5 republishes to the SAME url so the artifact stays a living page for this PR. --- ## Depth gate | Step | scan | medium | deep | |-----------------------------|-----------------------|---------------------|----------------------------| | Context: issue-tracker/CI/diff/existing-reviews | always | always | always | | Context: chat/docs/framework-docs/monitoring/prior-review-memory (optional, MCP-dependent) | skip | included | included + broader recall | | Worktree + static checks | skip (WORKTREE_PATH=null) unless `--fix` | included | included | | Review agents | 2 triage (haiku) | 5 specialists (sonnet) | 5 specialists (sonnet) | | Per-finding verification | none | Criticals only (hard rules exempt) | Criticals + Importants (hard rules exempt) | | Completeness critic | skip | skip | included | | Proof-of-bug (failing test per Critical) | skip | included (max 5) | included (max 5) | | Living review artifact | included | included | included | | Housekeeping (optional memory/notes writeback) | skip | included | included | | `--post` | supported | supported | supported | | `--fix` / fix offer | 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. --- ## Step 1 - Context + worktree (concurrent) Fire both tracks in the same turn. ### Track A - worktree setup (skip when depth=scan, unless `--fix`) Run via Bash with `run_in_background`: ```bash ${CLAUDE_PLUGIN_ROOT}/scripts/setup-worktree.sh \ /worktree.json [PREV_SHA] ``` On completion, read `worktree.json`. Keys emitted: `worktreePath`, `repoRoot`, `headSha`, `headShaShort`, `tscTail`, `tscChangedTail`, `tscErrorCount`, `eslintTail`, `eslintScope`, `changedFiles`, `baseRef`, `projectRules`, `deltaFile`, `notes`. 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: - `eslintTail` is the result of linting only `changedFiles` (`eslintScope` says `changed-files`). Everything in it belongs to this PR. When `eslintScope` is `full-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. - `tscTail` is the raw repo-wide tail (tsc needs the whole program, so it cannot be scoped). `tscChangedTail` holds only the errors in files this PR touched - that is the attributable set. `tscErrorCount` is the repo-wide total; a large count with an empty `tscChangedTail` means 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. 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). ### 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. - `gh pr view --repo ` with fields: `number`, `title`, `body`, `author`, `headRefName`, `baseRefName`, `labels`, `linkedBranches`, `mergeStateStatus`, `additions`, `deletions`, `changedFiles`, `isDraft`, `headRefOid`. Extract `headRefOid` (full sha) and `headShaShort` (first 7). - Title/ticket-prefix check (if `house-rules.md` defines one): scan commit log for the ticket pattern; set `PR_TITLE_ISSUE` and `RECOMMENDED_PREFIX`. - `gh pr diff --repo > /pr.diff` - fetched ONCE; all agents read this file via `DIFF_FILE`. - `gh pr checks --repo ` - `gh pr reviews --repo ` 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. ### Assemble CONTEXT_FILE Write `/context.json` with keys: ```json { "acList": "", "projectRules": "", "sentrySignals": "", "ciStatus": " | pending | N/A>", "existingReviews": "", "deltaFile": "", "houseRulesFile": "${CLAUDE_PLUGIN_ROOT}/references/house-rules.md" } ``` 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 - Workflow (review + verify + critic) Invoke the Workflow tool: ``` scriptPath: ${CLAUDE_PLUGIN_ROOT}/workflow.js args: { repoSlug, prNumber, prUrl, depth, diffFile: "/pr.diff", contextFile: "/context.json", worktreePath: , promptDir: "${CLAUDE_PLUGIN_ROOT}/references/agents", prevSha: } ``` Two optional args tune concurrency; omit both unless a run needs it: - `reviewBatchPlan` - batch sizes for the review dimensions, default `[5]` (all five at once). The last entry repeats to cover any remainder, so `[2]` would mean two at a time. - `maxConcurrent` - cap for the per-finding fan-outs (verify, critic, prove), default `5`. Lowering them is always safe: it costs wall-clock, never findings. Reach for that only when a specific run needs a smaller footprint. The workflow runs three phases: - **Review:** scan uses `[triage-quality, triage-logic]` on `haiku`; medium/deep use 5 specialists (quality, implementation, simplification, conventions, test-quality) on `sonnet`. Agents receive DIFF_FILE + CONTEXT_FILE by path. All five run concurrently: the stage is self-limiting at one agent per dimension. All reviewers run to completion before verification starts. Override per run with the `reviewBatchPlan` arg (e.g. `[1]` runs them strictly one at a time on a constrained machine). - **Dedup:** findings are merged across dimensions on `file:line` + title token-similarity, so one issue found by three agents is verified once, not three times. A merge keeps the highest severity and the longest description/badCode/fix of the set - a Critical is never demoted by an Observation someone else filed at the same line - and records every contributing dimension in `agreedBy`. - **Verify:** scan verifies nothing; medium verifies Criticals; deep verifies Criticals + Importants. Hard-rule findings (`rule` set) are always exempt. Each verifier runs the five-challenge adversarial refutation from `references/agents/verifier.md` against one finding, returns `{verdict, newSeverity?, reasoning}`. Verifiers run `maxConcurrent` at a time (default 5): this stage spawns one agent PER FINDING, so without a ceiling a thirty-finding PR launches thirty concurrent agents. - **Critic (deep only):** completeness critic gets the full deduped finding list + DIFF_FILE; its findings go through verifier agents before promotion. - **Prove (medium/deep, worktree required):** each non-hard-rule Critical gets one prover agent (`references/agents/prover.md`, sonnet, max 5, run `maxConcurrent` at a time) that writes a test asserting the CORRECT behaviour, runs it in the worktree, and captures it failing because of the bug. The proof rides on the finding as `proof: {attempted, proven, reason, testCode?, testCommand?, redOutput?}`. A proof that comes back GREEN (code behaved correctly) is counter-evidence - Step 3 must downgrade or explicitly justify the finding, never ignore it. Hard-rule findings are never proved (policy violations have no failing test). Findings have schema: `{file, line, severity, title, description, badCode, fix, rule?, precedent?, agreedBy?, verifierReasoning?, proof?}` `badCode` and `fix` are schema-required: an empty string is allowed only on `observation` / `idiomatic` findings. Model tiers: triage on `haiku`, specialists on `sonnet`, verifiers + critic + provers on `sonnet`, housekeeping on `haiku`. Only the synthesis in Step 3 runs on the session model. Return value from the workflow: `{findings, droppedCount, downgradedCount, hardRuleCount, proveAttemptCount, provenCount, agentCount, outputTokens, turnTokensTotal}` `outputTokens` is this workflow's own output spend; `turnTokensTotal` is the whole turn's shared pool (main loop included). Wait for the workflow to complete before proceeding to Step 3. --- ## Step 3 - Synthesize and output **Mindset:** the author's name is not evidence. Bot review scores are not anchors. Apply your own judgment to every finding. **Do NOT flag:** - Style preferences or naming taste where no convention is violated - Comment wording choices - Scenarios requiring multiple simultaneous unrealistic failures - Tiny DRY opportunities (2-3 duplicated lines) - Pre-existing code not touched by this diff - Anything you are not confident about - omit rather than hedge **Approval standard.** The verdict answers "does this definitely improve the codebase's health", not "is this how I would have written it". Perfect code does not exist. `โœ… LGTM - ship it` is the right call for a change that improves health and violates no hard rule, even with open Observations or Idiomatic findings. Reserve `๐Ÿšซ Needs work` for an unfixed Critical, a hard-rule violation, or an Important finding that changes external behaviour or data shape. Never manufacture a Critical to justify a verdict, and never block on taste. **PR sizing.** Judge how much a reviewer must hold at once, not the raw diff count: - Under ~300 changed lines, or larger but one logical change: no finding. - Over ~800 changed lines spanning more than one logical change: `important`, and name the split. Pick the strategy that fits - stack (sequential dependencies), by file group (different reviewers), horizontal (shared code and stubs first, then consumers), vertical (smaller full-stack slices). - A diff that both refactors existing code and adds new behaviour: `important` at any size. Those are two PRs, and bundling them hides the real change. - A change that pushes a single file past ~1000 total lines with no decomposition: `observation`. Ask for the extraction first, then the feature. Exempt: whole-file deletions and mechanical or automated refactors, where the reviewer verifies intent rather than every line. **Verify the verification.** Read the PR body for the author's verification story: which tests were run, whether the build passed, whether it was exercised manually, screenshots for a UI change, a before/after for a behaviour or performance change. A non-trivial PR whose body claims nothing about verification is an `observation` naming the evidence that is missing. `CI: โœ… All passing` is not a verification story - it only says the suite that already existed still runs. **Rationalizations to reject.** If one of these is the reason a finding is about to be dropped or softened, keep the finding: | Rationalization | Reality | |---|---| | "The tests pass, so it's fine" | Tests do not catch architecture, security, or data-shape problems. | | "It works, that's good enough" | Working code that is unreadable or insecure is debt that compounds. | | "The refactor makes it cleaner" | Relocating complexity is not reducing it. Count the concepts a reader holds. | | "It's only a small addition to this file" | Judge the resulting structure, not the diff size. | | "It's just a version bump" | A bump is a behaviour change nobody in the PR wrote. | | "They'll clean it up later" | Later does not come. Require it now, or require a ticket. | | "An agent wrote it, so it's probably fine" | Generated code needs more scrutiny, not less: it is confident and plausible when wrong. | **Idiomatic & Consistency exception:** the conventions agent raises non-blocking suggestions ONLY when a concrete better pattern provably already exists in the codebase. Never on taste alone. These land in their own section, not in Critical/Important. A finding without a cited precedent from the codebase is dropped. **Format** the review per `references/output-format.md` (read it now). Key requirements: - Header must include `**Head:** ` (enables future delta mode). - When `isDraft=true`: add `**DRAFT PR** - findings recorded for when this is ready to merge.` after the header block. - When `mergeStateStatus` is not CLEAN: note it (e.g. conflicts, failing required checks). - When `PR_TITLE_ISSUE=true`: insert the `โ›” CANNOT MERGE` block before the Summary. - When `sentrySignals` is non-empty: include `## ๐Ÿ”ฅ Production Signals`. - When `PREV_SHA` is set: include `## ๐Ÿ” Since last review` comparing `PREV_REVIEW_FILE` findings against the new head - list each as fixed or still open, before any new findings. - Test Quality section: populate from the test-quality agent's fields (`coverageVerdict`, `mutationSlip`, `mockSmells`). - Idiomatic section: populated from severity=idiomatic findings only. - **๐Ÿ’ฐ Review Cost block:** `outputTokens` from the workflow return is the ACTUAL output spend of the review workflow's own agents. `turnTokensTotal` is the whole turn's shared pool - report it separately, never as the workflow's cost. Input tokens are estimated (diff tokens x agent passes + context + prompt files). Use the pricing table in `references/output-format.md`. Real numbers only - no `` placeholders. **Save the review:** ```bash mkdir -p ~/code-reviews REVIEW_FILE=~/code-reviews/$(date +%Y-%m-%d)-pr--.md # write the review to $REVIEW_FILE ``` After writing, re-read the file and emit a receipt: `โœ“ Review saved -> ` Also write the workflow's `findings` array verbatim to `/findings.json` - fix mode reads its selection from there (the `proof` objects ride along for the Step 5b proof flip), and it is the receipt that what was reported equals what was found. Then print the full review as the response. --- ## Step 3.5 - Living review artifact (skip when ARTIFACT=false) Immediately after printing the review, follow `references/artifact-page.md`: launch ONE background sonnet agent that renders the review as a self-contained HTML page and publishes it via the Artifact tool - passing `PREV_ARTIFACT_URL` when set, so a re-review UPDATES the same page instead of minting a new URL. The page is the living version of the review: verdict header, since-last-review timeline, findings with proof panels, all private by default. Never block on it: the printed review and the saved file are the deliverable; the artifact is an enhancement. When the URL comes back, append/refresh the `**Artifact:** ` header line in the saved review file (re-read to confirm) and print one line: `๐Ÿ”— Living review: `. --- ## Step 4 - Fix mode (after the review is printed) ### Trigger - `FIX_MODE=true` (the user passed `--fix`) -> go straight to `references/fix-mode.md`. - `FIX_MODE=false` and at least one Critical or Important finding has a `fix` field -> ask once, via AskUserQuestion: > Apply these fixes to the PR branch? > - **Critical + Important** (N findings) - fix agents edit the worktree, > verified, committed; push needs your confirmation > - **Critical only** (N findings) > - **No, review only** Set `FIX_MODE=true` and `FIX_SCOPE=` from the answer. On "No", skip to Step 5. - No fixable findings, or the review found nothing -> do not ask. Say `nothing to auto-fix` in one line and skip to Step 5. - **Unattended run** (cron, `/loop`, background agent): never ask. Run fix mode only when `--fix` was passed explicitly, and stop before pushing. ### Procedure Read `references/fix-mode.md` and follow it. Shape of the run: 1. Preconditions: worktree exists + clean, `origin/` still at `headSha`, PR open, head repo writable. 2. Select eligible findings (Critical/Important with a `fix`, real file, non-generated). Never auto-fix Observation, Idiomatic, or a title/process rule. 3. Invoke the fix workflow: ``` scriptPath: ${CLAUDE_PLUGIN_ROOT}/fix-workflow.js args: { repoSlug, prNumber, worktreePath, diffFile, contextFile, promptDir, findings: [] } ``` One `sonnet` fix agent per file (never two on the same file), then a read-only `sonnet` fix-verifier per file reading the actual `git diff`. One retry max on a non-`good` verdict. 4. Revert every group the verifier did not pass. 5. Run `scripts/verify-fixes.sh /fix-verify.json tests` and diff the output against the baseline `tscTail`/`eslintTail` from worktree.json. Newly introduced errors -> revert that group. 5b. Proof flip: for findings with `proof.proven`, re-run the captured failing test after the fix. Still red -> the fix did not fix the bug: revert the group even if the fix-verifier said `good`. An executed test outranks an agent's opinion. Green -> record `proofFlip: green` in the status table. 6. Commit one commit per file with an explicit `git add -- `. 7. Push ONLY after the user confirms, with `git push origin HEAD:refs/heads/` and a re-fetch sha guard. Never force, never rebase, never push to main/master/staging/develop. Verify via `gh pr view --json headRefOid`. 8. Print the per-finding status table and append `## ๐Ÿ”ง Fixes applied` to the saved review file. Fix-agent tokens are additional spend: add a `Fix agents:` line to the `## ๐Ÿ’ฐ Review Cost` block. --- ## Step 5 - Post-review (after the review and any fixes) ### If POST_REVIEW=true Follow `references/github-post.md`: - Build a JSON payload with Critical + Important findings as inline comments (only for lines present in the diff hunks). - POST via `gh api repos//pulls//reviews` with NO `event` field (creates PENDING, visible only to you). - Verify post-condition: fetch review list, confirm PENDING state exists. - Print count + link. - Observation and Idiomatic findings go in the review body, never inline. - Never submit the review programmatically. - When fix mode applied and committed a finding, EXCLUDE it from the inline comments - do not ask for a change you already made. Mention the applied fixes in one line of the review body instead. ### Housekeeping (skip when depth=scan, optional) If you maintain a persistent notes/memory system across reviews, launch ONE background Agent with `model: 'haiku'`, passing the review file path + repo-short-name + PR author login, instructed to follow `references/post-review.md` if you've written one for your own setup: - Log durable patterns (recurring findings, confirmed false positives) scoped to the repo, never to the author. - Skip entirely if you have no such system: nothing else in this skill depends on it. ### Cleanup (when a worktree was created) **Fix-mode override:** if fix mode produced commits that were NOT pushed, do NOT clean up. Keep the worktree and the repo clone, print the worktree path and the exact push command. Deleting it destroys the only copy of the work. Clean up normally when the push succeeded or nothing was committed. ```bash git -C worktree remove --force \ || rm -rf git -C worktree prune ``` If `repoRoot` starts with `/tmp/lekker-clone-`, also remove that clone dir. Remove the delta file if `deltaFile` was set in worktree.json. Verify with `git -C worktree list` that no `lekker-review` entries remain. --- ## Failure rules Two identical failures = stop and diagnose, don't loop blindly. If the Workflow tool is unavailable or the run dies: first re-check that DIFF_FILE, CONTEXT_FILE and WORKTREE_PATH still exist. A killed run often means the session was torn down, and a teardown takes the worktree and scratchpad with it - agents launched against vanished inputs return nothing and the tokens are wasted. Re-run Step 1 before Step 2 if any input is missing. Once the inputs are confirmed present, fall back to launching the 5 agents via the Agent tool with the same prompt files, do verification inline per `references/agents/verifier.md`, and state this fallback in the review output under a `**Note:** Workflow tool unavailable - ran agents directly` line in the header. Fix-mode specific: - Never claim a fix landed without a `git log` / `git status` receipt from the worktree. The review's proposed `fix` text is not an applied fix. - Never push without explicit confirmation, and never force-push or rebase a PR branch. If the branch moved under you, stop and report - the commits stay local.