# How the Caveman-Review Skill Formats Comments: Syntax Guide and Examples > Learn how the caveman-review skill formats comments with its strict syntax L: . . Discover how to use severity emojis and avoid filler text. - Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman) - Tags: how-to-guide - Published: 2026-08-22 --- **The caveman-review skill produces ultra-compressed review comments using a strict line-oriented format: `L: . .` with optional severity emojis (πŸ”΄ bug, 🟑 risk, πŸ”΅ nit, ❓ q) and zero conversational filler.** The **caveman-review** skill is part of the [JuliusBrussee/caveman](https://github.com/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`](https://github.com/JuliusBrussee/caveman/blob/main/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: ```text L: . . ``` For example: ```text 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: ```text :L: . . ``` Example from the source documentation: ```text 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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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):** ```text 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):** ```text L42: πŸ”΄ bug: user can be null after .find(). Add guard before .email. ``` **Bad (verbose description):** ```text 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):** ```text 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: . .` or `:L: …` 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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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.