caveman-review
juliusbrussee/caveman
Compressed code review: one line per finding with location, problem, and fix.
What is caveman-review?
A code review skill that enforces terse, actionable feedback. One line per finding with exact location, concrete problem statement, and specific fix—no hedging or throat-clearing. Use it to review PRs, diffs, or code snippets with maximum signal and minimum noise.
- Format findings as `L<line>: <problem>. <fix>.` with optional severity prefix (🔴 bug, 🟡 risk, 🔵 nit, ❓ q)
- Strip filler language: no "I noticed", "you might consider", or restating what the code does
- Include exact line numbers, symbol names in backticks, and concrete fixes with rationale when non-obvious
- Expand to full paragraphs only for security findings, architectural disagreements, or onboarding contexts
- Output comments ready to paste directly into PR review tools
How to install caveman-review
npx skills add https://github.com/juliusbrussee/caveman --skill caveman-reviewHow to use caveman-review
- 1.Invoke with `/caveman-review`, "review this PR", or "review the diff"
- 2.Paste the code or diff you want reviewed
- 3.Read the one-line findings with location, problem, and fix
- 4.For security or architectural issues, expect a full paragraph instead of a one-liner
- 5.Use "stop caveman-review" or "normal mode" to revert to verbose review style
Use cases
- Review pull requests with rapid, focused feedback on bugs and risks
- Audit diffs across multiple files with consistent severity labeling
- Provide code review in high-velocity teams where verbose comments slow iteration
- Identify fragile patterns (race conditions, missing null checks, swallowed errors) in one-liner format
- Train junior developers on what actionable feedback looks like
- Code reviewers in fast-moving teams
- Engineering leads standardizing review culture
- Developers using Claude Code or Cursor for PR feedback
- Teams adopting terse communication norms
caveman-review FAQ
For security findings (CVE-class bugs need references), architectural disagreements (need rationale), and onboarding contexts where the author is new and needs the "why". Resume terse mode for the rest of the review.
🔴 bug = broken behavior causing incidents; 🟡 risk = works but fragile (race, null check, swallowed error); 🔵 nit = style/naming/micro-optimization (author can ignore); ❓ q = genuine question, not a suggestion.
No. Caveman-review outputs comments only—it does not write code, approve/request changes, or run linters. You paste the output directly into the PR.
Use the `❓ q:` prefix to frame it as a genuine question rather than a suggestion. Avoid hedging language like "perhaps" or "maybe".
Say "stop caveman-review" or "normal mode" to exit terse mode and resume verbose review comments.
Full instructions (SKILL.md)
Source of truth, from juliusbrussee/caveman.
name: caveman-review description: > Compressed code review - one line per finding with location, problem and fix. Use for /caveman-review, "review this PR", or "review the diff".
Write code review comments terse and actionable. One line per finding. Location, problem, fix. No throat-clearing.
Rules
Format: L<line>: <problem>. <fix>. — or <file>:L<line>: ... when reviewing multi-file diffs.
Severity prefix (optional, when mixed):
🔴 bug:— broken behavior, will cause incident🟡 risk:— works but fragile (race, missing null check, swallowed error)🔵 nit:— style, naming, micro-optim. Author can ignore❓ q:— genuine question, not a suggestion
Drop:
- "I noticed that...", "It seems like...", "You might want to consider..."
- "This is just a suggestion but..." — use
nit:instead - "Great work!", "Looks good overall but..." — say it once at the top, not per comment
- Restating what the line does — the reviewer can read the diff
- Hedging ("perhaps", "maybe", "I think") — if unsure use
q:
Keep:
- Exact line numbers
- Exact symbol/function/variable names in backticks
- Concrete fix, not "consider refactoring this"
- The why if the fix isn't obvious from the problem statement
Examples
❌ "I noticed that on line 42 you're not checking if the user object is null before accessing the email property. This could potentially cause a crash if the user is not found in the database. You might want to add a null check here."
✅ L42: 🔴 bug: user can be null after .find(). Add guard before .email.
❌ "It looks like this function is doing a lot of things and might benefit from being broken up into smaller functions for readability."
✅ L88-140: 🔵 nit: 50-line fn does 4 things. Extract validate/normalize/persist.
❌ "Have you considered what happens if the API returns a 429? I think we should probably handle that case."
✅ L23: 🟡 risk: no retry on 429. Wrap in withBackoff(3).
Auto-Clarity
Drop terse mode for: security findings (CVE-class bugs need full explanation + reference), architectural disagreements (need rationale, not just a one-liner), and onboarding contexts where the author is new and needs the "why". In those cases write a normal paragraph, then resume terse for the rest.
Boundaries
Reviews only — does not write the code fix, does not approve/request-changes, does not run linters. Output the comment(s) ready to paste into the PR. "stop caveman-review" or "normal mode": revert to verbose review style.
Related skills
More from juliusbrussee/caveman and the wider catalog.
