caveman-review ยท diff

git:20260905.8517930 to git:20260905.5a586b0

14 added, 37 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: caveman-review
description: >
Compressed code review - one line per finding with location, problem and fix.
Use for /caveman-review or when the user requests terse, one-line review findings.
Ordinary review requests use code-review.
---
- Write code review comments terse and actionable. One line per finding. Location, problem, fix. No throat-clearing.
-
- Use `code-review` for scope selection, source inspection, and validation when available. This skill controls presentation. Compression must preserve the failure scenario, evidence, and uncertainty needed to assess a finding.
-
- ## 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
+ # Terse review findings
- ## Examples
+ Use [code-review](../code-review/SKILL.md) for scope, contract tracing, evidence, severity, and coverage. This skill controls presentation, not review depth. If code-review is already active, format its results without restarting the review. If unavailable, inspect the requested diff and affected callers, verify reachable failure scenarios, and disclose coverage limits.
- โŒ "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."
+ ## Format
- โœ… `L42: ๐Ÿ”ด bug: user can be null after .find(). Add guard before .email.`
+ Write one line per finding: `<file>:<line>: [P1] <trigger and consequence>. <smallest fix>.`
- โŒ "It looks like this function is doing a lot of things and might benefit from being broken up into smaller functions for readability."
+ Use the repository's severity labels when defined. Keep exact symbols, evidence, and meaningful uncertainty. Severity describes impact, not confidence. Label a source-proven finding as such when it could be mistaken for an executed reproduction. Use `question:` for an unresolved assumption and `nit:` for an optional preference, never to disguise a speculative bug as a finding.
- โœ… `L88-140: ๐Ÿ”ต nit: 50-line fn does 4 things. Extract validate/normalize/persist.`
+ Group duplicate symptoms under their shared cause. Omit praise, restatements of the diff, generic cleanup advice, and arbitrary prescriptions such as a retry count unsupported by the operation's contract.
- โŒ "Have you considered what happens if the API returns a 429? I think we should probably handle that case."
+ Examples, only when the stated behavior is established by inspection:
- โœ… `L23: ๐ŸŸก risk: no retry on 429. Wrap in withBackoff(3).`
+ - `users.py:42: [P2] A missing user makes find() return None, then .email raises. Handle not-found before dereference; confirmed by source.`
+ - `save.ts:73: [P1] Save A's late response replaces newer B in the editor. Ignore responses for superseded revisions; reproduced with delayed A.`
+ - `client.py:23: question: Does the server deduplicate POST retries? Confirm before retrying an ambiguous timeout.`
- ## Auto-Clarity
+ A short finding still needs enough context to be checked. Use a paragraph when a security boundary, data-loss sequence, or architectural consequence cannot be explained accurately in one line. Resume terse output for other findings.
- 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.
+ ## Receipt and boundaries
- ## Boundaries
+ End with a compact scope/checks/gaps line. Identify the reviewed revisions or local layers and material unreviewed boundaries. If no actionable findings remain, say so with any coverage limits; do not replace this with an approval claim.
- Review without modifying product files or posting a review unless the user requests those actions. Focused checks with autofix disabled are allowed when useful to verify a finding. Output comments ready to paste into the PR. "stop caveman-review" or "normal mode": return to normal review prose.
+ Review without modifying product files, posting comments, or approving/requesting changes on the host unless authorized. Focused checks with autofix disabled may establish evidence. "stop caveman-review" or "normal mode" returns to normal review prose.