How the Caveman-Review Skill Formats Comments: Syntax Guide and Examples

The caveman-review skill produces ultra-compressed review comments using a strict line-oriented format: L<line>: <problem>. <fix>. with optional severity emojis (🔴 bug, 🟡 risk, 🔵 nit, ❓ q) and zero conversational filler.

The caveman-review skill is part of the JuliusBrussee/caveman repository, an open-source coding assistant framework. This skill is engineered to generate terse, actionable code review output that developers can paste directly into pull request comments. Understanding how the caveman-review skill formats comments ensures your AI-generated reviews remain consistent, scannable, and immediately useful.

Core Comment Format Structure

The caveman-review skill enforces a rigid, tokenized syntax defined in skills/caveman-review/SKILL.md. Every comment must follow precise structural rules to maintain the "caveman" aesthetic of minimal verbosity.

Basic Line Syntax

The fundamental unit is a single line reference followed by a problem statement and resolution:

L<line>: <problem>. <fix>.

For example:

L23: 🟡 risk: no retry on 429. Wrap in withBackoff(3).

The L prefix is mandatory and must immediately precede the line number without spaces. The problem description ends with a period, followed by the concrete fix recommendation.

Multi-File Diff Formatting

When reviewing changes across multiple files, prepend the file path to maintain context:

<file>:L<line>: <problem>. <fix>.

Example from the source documentation:

src/utils/auth.go:L57: 🔴 bug: nil pointer dereference on token.Validate().

This format ensures that even in multi-file pull requests, each comment unambiguously identifies its target location.

Severity Prefixes and Emoji Codes

The caveman-review skill supports four severity indicators that prepend the problem description. These emojis categorize the urgency and nature of the finding:

• 🔴 bug: Broken behavior that will cause an incident or crash in production.
• 🟡 risk: Fragile code patterns including race conditions, missing edge-case checks, or brittle logic.
• 🔵 nit: Style suggestions, micro-optimizations, or minor refactoring opportunities.
• ❓ q: Genuine questions requiring author clarification before approval.

According to skills/caveman-review/SKILL.md, these prefixes are optional but recommended when mixing findings of different severities in a single review session.

Content Guidelines: What to Keep and What to Drop

The skill applies aggressive content filtering rules to eliminate noise. Comments must retain technical precision while removing all social lubricant.

Required Elements

Every comment must preserve:

1. Exact line numbers (mandatory L prefix format)
2. Symbol names wrapped in backticks (e.g., user, validateToken())
3. Concrete fix instructions with a brief "why" only when the resolution is non-obvious

Prohibited Phrases

The following patterns are explicitly stripped according to the source rules in SKILL.md:

• Hedging language ("I noticed that…", "It seems like…", "Maybe consider…")
• Social pleasantries ("Great work!", "Nice job!", "Thanks!")
• Restatements of the diff (describing what the code already shows)
• Meta-commentary about the review process

Good vs Bad Examples

The caveman-review skill documentation provides concrete before-and-after comparisons illustrating the format.

Bad (conversational):

I noticed that on line 42 you're not checking if the user object is null before accessing properties. This could cause issues. Great work otherwise!

Good (caveman format):

L42: 🔴 bug: user can be null after .find(). Add guard before .email.

Bad (verbose description):

It looks like this function does a lot of different things and violates single responsibility principle. Maybe we should consider breaking it up?

Good (actionable compression):

L88-140: 🔵 nit: 50-line fn does 4 things. Extract validate/normalize/persist.

Note the use of line ranges (L88-140) for multi-line issues and the elimination of all filler words.

Operational Boundaries

As implemented in the JuliusBrussee/caveman source, the skill operates under strict constraints:

• Read-only: The skill only reviews code; it never writes the actual fix, generates diffs, or approves changes.
• No execution: It does not run linters, tests, or static analysis tools.
• Manual termination: To exit terse review mode, issue the command "stop caveman-review" or switch to normal conversational mode.

The output is designed for immediate copy-paste into GitHub, GitLab, or Bitbucket pull request comment fields.

Summary

• Format: Use L<line>: <problem>. <fix>. or <file>:L<line>: … for multi-file reviews.
• Severity: Prefix with 🔴 (bug), 🟡 (risk), 🔵 (nit), or ❓ (question) when categorizing findings.
• Symbols: Wrap all variable and function names in backticks.
• Tone: Eliminate hedging, praise, and meta-commentary.
• Scope: Review only; never generate patches or approval signals.
• Source: Rules defined in skills/caveman-review/SKILL.md.

Frequently Asked Questions

What is the exact syntax for single-line comments in caveman-review?

Single-line comments must start with an uppercase L immediately followed by the line number, a colon, and a space. The format is L23: problem description. concrete fix. File paths are omitted only when reviewing a single file context.

How do I indicate severity in caveman-review comments?

Prepend the problem description with one of four emoji codes: 🔴 for bugs, 🟡 for risks, 🔵 for nits, or ❓ for questions. Include a space after the emoji and before the category label (e.g., L42: 🔴 bug:).

Can caveman-review write the actual code fixes?

No. According to the skill definition in skills/caveman-review/SKILL.md, the tool is strictly read-only. It suggests fixes in natural language but never outputs patch files, code blocks containing solutions, or automated commits.

How do I exit terse review mode when using caveman-review?

To stop the terse formatting mode, explicitly state "stop caveman-review" or request that the assistant switch to normal conversational mode. This boundary is documented in the skill's operational constraints.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}