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).
In this repository5 other files it gives its agents.
- .agents/default/AGENTS.mdAGENTS.md
- AGENTS.mdAGENTS.md
- kronk-service-architectureSkill
- probing-kronkSkill
- use-modern-goSkill
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
- Very specific: line 15
Start from a fresh session: Every orchestrator turn re-reads the whole conversation.
- Distinctive: line 20
Runs are independent: Never open a previous run's files.
- Very specific: line 42
If a full review was requested without an extent, ask first.
- Very specific: line 77
If the builder replies ac_status=weak or missing, read <run>/context/ac-review.md, show its problems and suggested Given/When/Then …
- Distinctive: line 85
After checks finish, launch the chosen agents in one message.
- Very specific: line 99
If shards > 0, run correctness and tests once per shard.
- Very specific: line 113
If the generated-file scan was accepted, also launch: "Follow <skill>/references/roles/generated-scan.md.
≈ “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.
Files
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 theF…headings offindings.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 whenscope.txtsaystrust=maintainer: intake sets it for--prwhen 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 editscope.txtor 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 forchecks.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_WORKSPACEis set to the repo root for every check.- Tests run only for a maintainer's PR (
trust=maintainer), asgo test -race -short -count=1on the reviewed packages only (the changed ones atdiffdepth), never./...and never atprojectdepth (AGENTS.mdforbids a full repo test run), withKRONK_BASE_PATHpointed at an empty store so in-package model-backed tests skip instead of running inference. Packages undersdk/kronk/tests,sdk/bucky/tests,sdk/kronk/pool, andcmd/server/api/services/kronk/testsare never tested: they need native libraries, models, or a server, and belong to CI or humans. - Go static checks follow CI's
staticjob:go vet ./...per module (as CI runs it), and on the reviewed packages onlystaticcheck -checks=all,go fix -diff,govulncheck; plusgofmt -s -lon the reviewed files (AGENTS.mdadds-s) andgo mod tidy -diff.goreleaser checkis not run. Build output goes to/dev/null, so checks never write to the repo. For a maintainer's PR, BUI TypeScript changes also gettsc --noEmitwhennode_modulesexists, and Helm chart changes getzarf/helm/kronk/test.shwhen Python's PyYAML is installed (any chart getshelm lintand a render). - Generated outputs (BUI docs components,
cli-reference.json, the embeddedstatic/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.
- Ticket link — always ask if none was given (normally an
ardanlabs/kronkGitHub issue). "No ticket" is valid: spec review then works best-effort from the PR description and commits. - 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_linestoo). - Size — if
size_warnings > 0, followreferences/size-guard.md. - 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 instack.mdfor reviewers to read and never run. - 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.
- 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.mdsays only "Security issues detected."; details only insecurity-issues/) · named (security issues listed infindings.mdanddiagrams.mdlike any finding).
- Generated files — if
skipped.tsvhas generated or vendored rows (noiserows in the size table), say how many are skipped and ask: Skip (default) · Secret-scan only (cost ≈noise_tokens_est; a secret scanner intools.tsvmakes 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. - 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.
- Security PoC target — All agents + Security with
trust=maintaineronly, and only if memory has nokronk-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 memorykronk-project-interaction-guide(no memory → ask every run). Never ask about test setup:checks.shalready 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
intake.sh <scope> --id <id> [--depth <depth>] [--exclude <path>]… [--include-generated]creates<run>.checks.shreads the depth fromscope.txt.- 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 exit3/4, write the text between===== stack.md =====and===== extra-checks.tsv =====to<run>/context/stack.mdand the rest up to===== end =====to<run>/context/extra-checks.tsv, verbatim. - Save the ticket raw to
<run>/context/ticket.mdwithout reading it —gh issue view <n> --repo ardanlabs/kronk --comments > …first, then a tracker MCP, then web fetch. - In parallel:
checks.sh <run> [--exclude <pkg path>]… [--timeout D] [--extra <approved names>|all]in the background (it readstrustfromscope.txtitself), 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.
| Agent | Checklists (references/lenses/) | Routed when |
security | security-sentinel | All agents + Security only |
spec | spec-cartographer | ticket given (then mandatory) |
correctness | service-steward, + error-tripwire if failure=1, + boundary-keeper if contract=1 | prod_files > 0 (infrastructure counts) |
tests | harness-map | prod_files > 0 or test_files > 0 |
polish | clone-hunter if logic=1, doc-drift-check if comments=1; straight-line-pass in All agents/Polish only | logic=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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

