caveman-review

Engineering Community

Repo stars 68,344
Author repo caveman

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: > Write code review comments terse and actionable. One line per finding. Location, problem, fix. No throat-clearing. ❌ "I notice…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “Rules”, “Examples”, “Auto-Clarity”, “Boundaries”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name caveman-review directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “Rules / Examples / Auto-Clarity” before expanding.

Boundaries And Review

Dependencies: It usually needs no extra API key, so start with a small validation task.
Permissions: Declared permissions include read / write; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

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.

Fluxly profile Author and license come from source; runtime, permissions, and network are Fluxly detections or estimates

Fluxly category: Engineering
Author-declared agents: No explicit declaration found; this is not inferred or tested compatibility
Static check: 88 / 100 · heuristic scan, not runtime safety proof
Author / version / license: @JuliusBrussee · no license declared
Fluxly token estimate: Lean
Fluxly setup estimate: Plug-and-play
External API key: No requirement detected
Detected OS requirements: Unspecified
Runtime requirements: Unspecified
Detected file/system behavior: Read-only
Write / modify
Detected network behavior: Local-only
Install commands: None (reference only)

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview caveman-review.preview

The current SKILL.md does not define a fixed output example.

SKILL.md SKILL.md

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

…

Evidence boundary and execution chain

Author text anchors workflow facts; Fluxly only indexes current sections, terms, files, and commands.

sections -> Rules → Examples → Auto-Clarity → Boundaries
terms    -> Format · Severity prefix (optional, when mixed) · Drop · Keep
files/cmd -> L<line>: <problem>. <fix>. · <file>:L<line>: ... · 🔴 bug: · 🟡 risk: · 🔵 nit: · ❓ q: · nit: · L42: 🔴 bug: user can be null after .find(). Add guard before .email.
body sha256 -> 045a9cbe4d51