Caveman-Review PR Comment Format: Structure and Implementation

The /caveman-review command generates one-line, machine-readable comments following the pattern L<line>: <severity> <problem>. <fix>., utilizing four severity codes (bug, risk, nit, q) or returning LGTM when no issues are found.

The caveman repository provides an automated code review tool that enforces a strict, machine-readable output format for PR comments. When developers invoke the /caveman-review slash command, the bot analyzes the current diff and emits findings according to specifications defined in commands/caveman-review.md and commands/caveman-review.toml.

Understanding the Caveman-Review Comment Structure

The /caveman-review command produces comments that follow a strict, lightweight structure designed for programmatic parsing. This format deliberately omits praise, "obvious" notes, or multi-line explanations to keep outputs lightweight and easy to process by downstream tools.

The One-Line Pattern

Each comment adheres to the following format:

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

The pattern components include:

• L<line> – The line number prefixed with a capital "L" (e.g., L42)
• <severity> – One of four allowed severity codes
• <problem> – A concise description of the issue (no period)
• <fix> – A short suggestion for resolution (ends with a period)

Severity Levels and Codes

The format supports four distinct severity codes as defined in the command metadata:

• bug – An actual defect that will break the program
• risk – A risky construct that could cause future problems
• nit – A stylistic or minor improvement
• q – A question or clarification request

Source Code Implementation

The comment format is enforced through several key files in the JuliusBrussee/caveman repository.

Command Definition Files

In commands/caveman-review.md, the human-readable description outlines the expected comment format. The corresponding commands/caveman-review.toml (lines 1-3) contains the machine-readable metadata used by the Opencode plugin to validate outputs.

Parsing and Mode Handling

The slash command parsing occurs in src/plugins/opencode/plugin.js at lines 46-48, where /caveman-review is mapped to the "review" mode. The mode transition and output flow are handled by src/hooks/caveman-mode-tracker.js at lines 117-124, ensuring the bot emits only the structured one-line comments without additional formatting.

Practical Examples

The following examples demonstrate valid /caveman-review outputs for different scenarios.

Reporting a Bug

L42: bug Missing semicolon. Add ';' at the end of the statement.

Highlighting a Risk

L108: risk Unchecked user input could cause XSS. Sanitize the input before use.

Stylistic Nitpick

L7: nit Use `const` instead of `let`. Improves readability.

Asking a Question

L23: q Why is this function called here? Clarify intent or rename.

No Issues Found

When the diff contains no actionable items, the bot returns:

LGTM

Summary

• The caveman-review PR comment format requires one-line outputs following the pattern L<line>: <severity> <problem>. <fix>.
• Four severity codes are supported: bug, risk, nit, and q
• The format is defined in commands/caveman-review.md and enforced by the Opencode plugin in src/plugins/opencode/plugin.js
• Empty results return LGTM to indicate approval
• The structure deliberately excludes multi-line explanations to maintain machine readability

Frequently Asked Questions

What is the exact syntax for caveman-review PR comments?

The exact syntax requires a line number prefixed with "L", followed by a colon, one of four severity codes, a problem description without a period, and a fix suggestion ending with a period. For example: L42: bug Missing semicolon. Add ';' at the end of the statement.

What severity levels does the caveman-review format support?

The format supports four severity levels: bug for actual defects, risk for potentially dangerous constructs, nit for minor stylistic improvements, and q for questions or requests for clarification.

How does the bot indicate that no issues were found?

When the diff contains no actionable items, the bot simply replies with LGTM (Looks Good To Me) and stops processing, providing a clear signal that the code passes the automated review.

Where is the comment format defined in the source code?

The format specification resides in commands/caveman-review.md (human-readable description) and commands/caveman-review.toml (machine-readable metadata). The parsing logic that enforces this format is implemented in src/plugins/opencode/plugin.js (lines 46-48), while the mode handling occurs in src/hooks/caveman-mode-tracker.js (lines 117-124).

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