Issue 07 | /caveman-review — Single-line Code Review

🎯 Learning Objectives

After this issue, you will master:

1. /caveman-review's output format and severity level system
2. How to trigger code reviews on different platforms
3. Hands-on: Reviewing an Express middleware code snippet
4. Integrating with GitHub Actions for automated PR reviews

📖 Core Content

7.1 Why Caveman for Code Review?

Problems with traditional AI code review:

❌ Normal Claude's code review (each issue is a long paragraph):

"I noticed that on line 42, you're accessing `user.name` without 
first checking if the `user` object is null or undefined. This could 
lead to a TypeError at runtime if the database query returns no results. 
I'd suggest adding a null check before accessing the property, perhaps 
using optional chaining (`user?.name`) or an explicit guard clause..."

(120 tokens to describe a null pointer issue)

Caveman's response:

✅ L42: 🔴 bug: user null. Add guard.

(10 tokens. Same issue.)

7.2 Output Format Specification

L<line_number>: <severity_level> <type>: <one-line_diagnosis>. <fix_suggestion>.

Severity Level System

graph LR
    subgraph Levels["Severity Levels"]
        A["🔴 bug
Must fix
Leads to runtime errors"]
        B["🟡 warn
Recommended fix
Potential issues or performance traps"]
        C["🔵 nit
Optional optimization
Code style or naming"]
        D["✅ ok
Good code
No changes needed"]
    end
    
    A --> B --> C --> D

7.3 Hands-on: Reviewing an Express Middleware

Code to be reviewed:

// auth.middleware.js
const jwt = require('jsonwebtoken');
const db = require('./database');

module.exports = async (req, res, next) => {
  const token = req.headers.authorization;          // L6
  
  try {
    const decoded = jwt.verify(token, SECRET);       // L9
    const user = await db.findUser(decoded.id);      // L10
    req.user = user;                                 // L11
    req.userRole = user.role;                        // L12
    next();                                          // L13
  } catch (err) {
    res.status(401).json({ error: err.message });    // L15
  }
};

🪨 Caveman Review Output:

L6:  🔴 bug: no Bearer prefix strip. `authorization` includes "Bearer ".
     Split: `token.split(' ')[1]`
L9:  🔴 bug: SECRET undefined. Should be `process.env.JWT_SECRET`.
L10: 🟡 warn: no user found check. `findUser` may return null → L12 crash.
L12: 🔴 bug: `user.role` throws if user null. Guard after L10.
L15: 🟡 warn: leaking jwt error details to client. Use generic message.
     `{ error: "Authentication failed" }`

Summary: 3 🔴 3 🟡. Auth middleware has critical null-safety gaps.

Compared to normal Claude's output which takes about 500+ tokens, Caveman achieves the same depth of review in only about 80 tokens.

7.4 Usage on Various Platforms

Claude Code

# Review current staged changes
> /caveman-review

# Review a specific file
> /caveman-review src/middleware/auth.js

# Review a PR's diff
> Review the changes in this PR, using caveman-review format

Antigravity

# Triggered by natural language
> Review src/middleware/auth.js in caveman-review format

# Or more concisely
> review auth.js, caveman style, one line per issue

Gemini CLI

> /caveman-review
# Or
> /caveman-review src/middleware/auth.js

Codex

> $caveman-review
# Or review a specific file
> $caveman-review src/middleware/auth.js

OpenCode

# Triggered by natural language (no slash command)
> Review current changes, format: L<line_number> + level(🔴🟡🔵) + one-line diagnosis

7.5 Integrating with GitHub Actions

Integrate caveman-review into your CI/CD to automatically get one-line reviews for every PR:

# .github/workflows/caveman-review.yml
name: Caveman Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: Get changed files
        id: diff
        run: |
          echo "files=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | tr '\n' ' ')" >> $GITHUB_OUTPUT
      
      - name: Caveman Review
        uses: anthropics/claude-code-action@v1
        with:
          prompt: |
            Review these changed files using caveman-review format.
            Rules:
            - One line per issue: L<line>: <🔴|🟡|🔵> <type>: <diagnosis>
            - No throat-clearing, no pleasantries
            - End with summary: N 🔴 N 🟡 N 🔵
            
            Files: ${{ steps.diff.outputs.files }}
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

graph TD
    A["Developer submits PR"] --> B["GitHub Actions triggered"]
    B --> C["Get changed files"]
    C --> D["Call Claude Code Action
+ caveman-review rules"]
    D --> E["Generate one-line review comments"]
    E --> F["Automatically comment on PR"]
    F --> G["Developer receives concise feedback"]
    
    G -->|"Push after fixing"| A

📊 Five-Platform Review Workflow Comparison

💡 Advanced Tips

Focus only on Bugs

> /caveman-review # Only report 🔴 level issues

Review by File Type

> /caveman-review *.tsx  # Only review React components
> /caveman-review *.sql  # Only review SQL files

Custom Review Dimensions

> /caveman-review Focus on: security vulnerabilities, SQL injection, XSS

📝 Key Takeaways from This Issue

1. /caveman-review output format: L<line_number>: 🔴/🟡/🔵 Type: One-line diagnosis
2. Three severity levels: 🔴 bug (must fix) / 🟡 warn (recommended) / 🔵 nit (optional)
3. For the same depth of review, Token consumption reduced by 80%+
4. Can be integrated with GitHub Actions for automated PR reviews
5. Codex uses $caveman-review, Antigravity and OpenCode use natural language triggers

🔗 References

• Caveman Review Skill
• Claude Code Action (GitHub)
• Conventional Comments