agentleFS
ardanlabsardanlabs/kronk/.agents/skills/kronk-pr-review/SKILL.md

kronk-pr-review

Skill868 starsChanged 14 days agoApache-2.0View on GitHub

Guided, read-only Kronk PR/diff review (Kronk DiffGuard), written for Claude Code subagents. Reviews only the change (plus unchanged code it breaks or the issue requires) unless a full review is requested (changed files, changed packages, or whole project). Scripts classify the change and run CI's Go static checks plus each ecosystem's own static analysis once; tests and other checks that run the reviewed code run only for a maintainer's PR (never model-backed suites like sdk/kronk/tests). A discovery agent finds the repo's own quality gates. Parallel agents review acceptance criteria (BDD, incl. required behavior missing from unchanged files), correctness against Kronk ownership and inference invariants, errors, comments and manual drift, tests, SDK/HTTP contracts, duplication, simplification, and optionally security, using per-language idioms (Go, React/TS, Helm, Docker, CI, shell, …). Asks for the GitHub issue, flags weak criteria and oversized changes, skips generated files unless the user opts in, writes an issues-only report plus Mermaid diagrams to .reviews/<id>/<NNN>/. USE for any review request: \"review this PR\", \"review my changes\", \"pre-commit review\", \"is this PR too big\", or one aspect (security, tests, errors, duplication).

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 2 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Start from a fresh session: Every orchestrator turn re-reads the whole conversation.

    line 15
  2. Distinctive:

    Runs are independent: Never open a previous run's files.

    line 20
  3. Very specific:

    If a full review was requested without an extent, ask first.

    line 42
  4. Very specific:

    If the builder replies ac_status=weak or missing, read <run>/context/ac-review.md, show its problems and suggested Given/When/Then …

    line 77
  5. Distinctive:

    After checks finish, launch the chosen agents in one message.

    line 85
  6. Very specific:

    If shards > 0, run correctness and tests once per shard.

    line 99
  7. Very specific:

    If the generated-file scan was accepted, also launch: "Follow <skill>/references/roles/generated-scan.md.

    line 113

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

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

Kronk PR Review

Written for Claude Code (subagents, project memory, agent transcript files); in another runtime, run the roles yourself and use step 7's manual fallback.

You are the orchestrator: scripts do the mechanical work once, a context builder writes a shared brief, review agents run in parallel and write files, an aggregator verifies and writes the report and diagrams. <skill> = this file's directory; <run> = <project-root>/.reviews/<id>/<NNN> (printed by intake).

Rules for you:

  • Start from a fresh session. Every orchestrator turn re-reads the whole conversation; inside a long session that costs more than the agents. If the conversation already holds unrelated work, suggest /clear (or a new session) before starting.
  • Keep your context small. Read only script output, agents' replies (one line; the discovery agent's and the aggregator's also carry blocks you only save), ac-review.md (when ACs are weak/missing), references/size-guard.md (when there are size warnings), and the F… headings of findings.md. Never read the diff, brief, check logs, or agent reports.
  • Advisory only. Nothing here edits, stages, or commits code, and nothing deploys, applies, or plans infrastructure.
  • Never run the reviewed code unless it's a maintainer PR. Tests, cargo commands other than cargo-audit, Terraform init/validate, linter plugins and repo-configured checks (golangci-lint, buf, checkov), repo gates, and security PoCs run only when scope.txt says trust=maintainer: intake sets it for --pr when GitHub reports the PR author has write access and the head branch is in the base repo. Every other scope is untrusted; the read-only checks still run. Never edit scope.txt or work around it — to run the code, review it as a maintainer's PR.
  • The change, not the codebase. By default only the change is reviewed (contract.md → Review scope). Problems that predate it are dropped, not reported. Only an explicit full-review request widens that.
  • Runs are independent. Never open a previous run's files.

Scripts take the same options in both shells (PowerShell spells them -Base, -DryRun, …; lists comma-separated). Run them inside the target repo:

  • sh: sh <skill>/scripts/intake.sh …, sh <skill>/scripts/checks.sh <run> …
  • PowerShell 7: pwsh -NoProfile -ExecutionPolicy Bypass -File <skill>/scripts/intake.ps1 … (same for checks.ps1; verified on pwsh 7 only)

Kronk rules the scripts apply on their own (from AGENTS.md and the Linux CI static/race jobs), so never ask about them or pass them by hand:

  • GITHUB_WORKSPACE is set to the repo root for every check.
  • Tests run only for a maintainer's PR (trust=maintainer), as go test -race -short -count=1 on the reviewed packages only (the changed ones at diff depth), never ./... and never at project depth (AGENTS.md forbids a full repo test run), with KRONK_BASE_PATH pointed at an empty store so in-package model-backed tests skip instead of running inference. Packages under sdk/kronk/tests, sdk/bucky/tests, sdk/kronk/pool, and cmd/server/api/services/kronk/tests are never tested: they need native libraries, models, or a server, and belong to CI or humans.
  • Go static checks follow CI's static job: go vet ./... per module (as CI runs it), and on the reviewed packages only staticcheck -checks=all, go fix -diff, govulncheck; plus gofmt -s -l on the reviewed files (AGENTS.md adds -s) and go mod tidy -diff. goreleaser check is not run. Build output goes to /dev/null, so checks never write to the repo. For a maintainer's PR, BUI TypeScript changes also get tsc --noEmit when node_modules exists, and Helm chart changes get zarf/helm/kronk/test.sh when Python's PyYAML is installed (any chart gets helm lint and a render).
  • Generated outputs (BUI docs components, cli-reference.json, the embedded static/ bundle, *.pb.go, gomod2nix.toml) are skipped like any generated file; a changed source without its regenerated output is a reviewer finding.

1. Parse the request

Note what was given: scope (default: all uncommitted changes, staged and unstaged, plus untracked; or --staged, --base <ref>, --range A..B, --pr <n>, --files <paths>), review depth, ticket, issue id, agent set, security mode, model tier, exclusions.

Review depth is diff (changes only) unless the user explicitly asks for a full review: --full-code, "full review", "full code review", or "review the whole file / package / project". Picking every agent (All agents) is not a full review. A request that names the extent maps straight to a depth: files → files, packages → packages, project or repo → project. Otherwise ask in step 2.

2. Preview

If a full review was requested without an extent, ask first; the preview needs the answer: Changed files (default) · Changed packages (every file in their directories) · Whole project (no tests run). Map the answer to --depth files|packages|project.

intake.sh --dry-run <scope> [--depth <depth>] [--id <ticket id>] writes nothing. On exit 3 the reviewed code isn't checked out: relay the printed command and stop. On 4 there is nothing to review: say so and stop. On 2 fix the arguments. Unless trust=maintainer, say in one line that checks which run the code (tests, builds, Terraform init, plugins, repo gates) will be skipped, with trust_reason.

Discovery. Then launch the discovery agent, on a cheaper model when your runtime picks models per subagent (it reads configs only): "Follow <skill>/references/roles/discovery.md. Skill directory: <skill>. Repo root: <root>. Review depth: <…>. Preview: <the languages=, ecosystems=, idioms= lines and the # stack and # unmapped rows, verbatim>." Wait for its reply (step 3 offers its repo gates; step 4 saves it).

Missing tools come first. If missing_tools > 0 or discovery lists Missing analyzers, before any question show them as one table (tool, what it checks, install command) and say: install them now and they are used by this run; the review goes ahead either way, and a missing tool's checks show as skipped. Rows marked rebuild are installed but built with an older Go than the active toolchain, so they fail on its standard library — the same install command rebuilds them. A cgo row means go test -race will fail until a C compiler is available. Rows whose purpose says optional, not in CI are extra analyzers: name them in one line and don't push installs; their package-wide output is filtered to in-scope code by the reviewers.

3. Ask

One round (native question UI if available, ≤3 batches). Skip what the request already answered.

  1. Ticket link — always ask if none was given (normally an ardanlabs/kronk GitHub issue). "No ticket" is valid: spec review then works best-effort from the PR description and commits.
  2. Scope and id — confirm the preview's scope, counts, id (ticket id, else branch name — same work, same directory), and depth (at full depth, review_files / review_lines too).
  3. Size — if size_warnings > 0, follow references/size-guard.md.
  4. Repo gates — only with trust=maintainer, if discovery proposed extra checks: list each (name, command, source) and ask which to run (all · pick · none; default none). Otherwise they stay in stack.md for reviewers to read and never run.
  5. Agents — Routed · All agents · All agents + Security · Partial (see step 6), naming the agents and checklists in each option, and saying when the small-diff merge applies. Partial asks a follow-up: Risk only or Polish only.
  6. Security — only with All agents + Security; then ask:
    • fan-out: single · capped (≤3 attacker sub-agents) · full (attacker + refuter per route);
    • report: redacted (default — findings.md says only "Security issues detected."; details only in security-issues/) · named (security issues listed in findings.md and diagrams.md like any finding).
  7. Generated files — if skipped.tsv has generated or vendored rows (noise rows in the size table), say how many are skipped and ask: Skip (default) · Secret-scan only (cost ≈ noise_tokens_est; a secret scanner in tools.tsv makes it much cheaper) · Review them too — re-run the preview with --include-generated, show the new counts and token estimates, and confirm before going on. Symlinks are never reviewed.
  8. Model tier — if your runtime picks models per subagent: run the context builder and generated-file scan on a cheaper model? Every run. Reviewers and the aggregator always use the session model.
  9. Security PoC target — All agents + Security with trust=maintainer only, and only if memory has no kronk-project-interaction-guide: is a disposable local Kronk server running for PoCs (host, port, how to get a token), or are PoCs static-only? Save the answer as project memory kronk-project-interaction-guide (no memory → ask every run). Never ask about test setup: checks.sh already applies the Kronk rules above.

The answers are the confirmation; echo the final setup in ≤6 lines and continue. If they change the scope or depth, re-run the preview and discovery first.

4. Prepare

  1. intake.sh <scope> --id <id> [--depth <depth>] [--exclude <path>]… [--include-generated] creates <run>. checks.sh reads the depth from scope.txt.
  2. Save the discovery reply without re-typing it: sh <skill>/scripts/extract-findings.sh --discovery <its output_file> <run> (PowerShell: -Discovery). With no transcript file, or on exit 3/4, write the text between ===== stack.md ===== and ===== extra-checks.tsv ===== to <run>/context/stack.md and the rest up to ===== end ===== to <run>/context/extra-checks.tsv, verbatim.
  3. Save the ticket raw to <run>/context/ticket.md without reading it — gh issue view <n> --repo ardanlabs/kronk --comments > … first, then a tracker MCP, then web fetch.
  4. In parallel: checks.sh <run> [--exclude <pkg path>]… [--timeout D] [--extra <approved names>|all] in the background (it reads trust from scope.txt itself), and the context builder: "Follow <skill>/references/roles/context-builder.md. Run directory: <run>."

5. Acceptance-criteria gate

If the builder replies ac_status=weak or missing, read <run>/context/ac-review.md, show its problems and suggested Given/When/Then criteria, and ask:

  • I'll fix the ticket — suggest pasting the BDD criteria in, so each can be reported Met / Partial / Unmet. Once done, re-fetch the ticket and tell the builder: "Refresh only the acceptance criteria in brief.md and ac-review.md from the updated ticket."
  • Use the suggestions for this run — no builder re-run: give spec and the aggregator Criteria in force: suggested BDD (context/ac-review.md).
  • Proceed as-is — spec reviews the criteria as written and reports their weaknesses.

6. Review agents

After checks finish, launch the chosen agents in one message.

AgentChecklists (references/lenses/)Routed when
securitysecurity-sentinelAll agents + Security only
specspec-cartographerticket given (then mandatory)
correctnessservice-steward, + error-tripwire if failure=1, + boundary-keeper if contract=1prod_files > 0 (infrastructure counts)
testsharness-mapprod_files > 0 or test_files > 0
polishclone-hunter if logic=1, doc-drift-check if comments=1; straight-line-pass in All agents/Polish onlylogic=1 or comments=1

Routed: the non-security agents whose condition holds. All agents: every agent and checklist except security (spec best-effort without a ticket). All agents + Security: All agents plus security. Partial → Risk only: spec, correctness, tests; Polish only: spec, polish. Only All agents + Security runs security; spec is never dropped when there is a ticket. The agent set never changes the review depth.

Small diff (code_lines_changed ≤ 150 at diff depth; at full depth, review_code_files ≤ 5 and review_lines ≤ 600): run the chosen correctness and tests checklists as one review agent — each agent costs a full context before it reads anything. Security, spec, and polish stay separate (polish findings get crowded out when merged).

If shards > 0, run correctness and tests once per shard.

Prompt:

You are the <agent> reviewer in a PR review run.
Read <skill>/references/contract.md, then <skill>/references/lenses/<a>.md[, …].
Idioms: <skill>/references/langs/<name>.md[, …] (from scope.txt idioms=)[, <run>/context/stack.md (when saved)].
Run directory: <run>. Shard: <k | all>. Review depth: <diff | files | packages | project>.
Write your report to <run>/lenses/<agent>[-<k>].md and reply with the one line the contract specifies.

Append for security: Fan-out: <mode>. Trust: <scope.txt trust>. Project interaction guide: <memory text, only with trust=maintainer | none>. PoCs only under <run>/security-issues/poc/<name>/. For spec: Criteria in force: <ticket | suggested BDD (context/ac-review.md) | best-effort>.

If the generated-file scan was accepted, also launch: "Follow <skill>/references/roles/generated-scan.md. Run directory: <run>. Skill directory: <skill>." No other agent reads generated files.

7. Aggregate and draw

Aggregator: "Follow <skill>/references/roles/aggregator.md. Run directory: <run>. Skill directory: <skill>. Review depth: <…>. Criteria in force: <…>. Security: <off | redacted | named>." It verifies the findings, writes security-issues/ (when security ran) and diagrams.md, and returns findings.md in its reply instead of writing it (some runtimes refuse subagent writes of report files). Before launching the aggregator, if any reviewer's reply says its write was refused, save the report from that reply verbatim to <run>/lenses/<agent>[-<k>].md.

Save findings.md without re-typing it: if your runtime gives the aggregator's transcript as a file (Claude Code: the agent's output_file), run sh <skill>/scripts/extract-findings.sh <output_file> <run> (PowerShell: extract-findings.ps1). On exit 3 (no jq) or 4, or with no transcript file, write the text between ===== findings.md ===== and ===== end ===== to <run>/findings.md verbatim — no edits, no summary. If a subagent says a write was refused, never have it, or anyone, retry through Bash; tell the user.

8. Report

From its reply and rg '^#### F' <run>/findings.md: review depth, overall Gate, counts per Gate, G4/G3 titles, the security-issue count (titles only in named mode), AC verdict counts, size warnings, and the paths to findings.md, diagrams.md, and security-issues/. If reopened is not no, offer to re-run the agent it names. Don't restate the report.

Run layout

<project-root>/.reviews/<id>/<NNN>/     NNN increments per run; never overwritten
  findings.md                    issues only; the AC table is the one place "Met" appears;
                                 in *redacted* mode security issues appear only as "Security issues detected."
  diagrams.md                    green added, red removed, amber modified, purple ⚠ findings (security only in *named* mode)
  security-issues/               only when security review ran
  security-issues/issue-NNN.md   one file per verified security finding
  security-issues/open-checks.md unproven security suspicions
  security-issues/poc/<name>/    optional PoCs
  lenses/<agent>[-<k>].md        raw agent reports
  context/                       scope.txt files.tsv skipped.tsv symbols.tsv refs.tsv signals.txt shards.tsv
                                 size.tsv packages.tsv stack.tsv unmapped.txt rules.txt tools.tsv missing.tsv
                                 diff.patch generated.patch review-set.tsv (full depth)
                                 stack.md extra-checks.tsv (discovery)
                                 ticket.md pr.md commits.txt brief.md ac-review.md checks/

Generated and vendored files (lockfiles included) are not reviewed unless the user opts in (step 3): intake moves them to skipped.tsv and generated.patch. Symlinks are never reviewed. Never open a symlink in the reviewed repo: its target can be outside the repo.

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.