Understanding the Severity Prefixes (🔴/🟡/🔵/❓) in caveman-review Comments

The caveman-review tool uses four emoji prefixes—🔴 bug, 🟡 risk, 🔵 nit, and ❓ question—to instantly communicate the severity and nature of each code review finding.

When you run code reviews in the JuliusBrussee/caveman repository, the caveman review command annotates every generated comment with a colored emoji that signals how critical the issue is. These severity prefixes in caveman-review comments follow a strict classification defined in the skill configuration, allowing developers to prioritize fixes at a glance without parsing lengthy explanations.

What Each Severity Prefix Means in caveman-review

The canonical definitions are established in skills/caveman-review/SKILL.md at lines 17‑20, with additional context in skills/caveman-review/README.md. Each emoji maps to a specific classification that determines how the author should respond.

🔴 Bug — Critical Defects

🔴 (Red circle) marks a bug—broken behavior that will cause an incident or defect and must be fixed before merge. These represent hard errors or guaranteed runtime failures.

🟡 Risk — Fragile Code

🟡 (Yellow circle) indicates risk—code that functions today but is fragile. This includes race conditions, missing null checks, swallowed errors, or patterns that could escalate into production problems under future changes.

🔵 Nit — Style and Polish

🔵 (Blue circle) denotes a nit—stylistic, naming, or micro-optimization issues. These are optional suggestions that authors can ignore without functional impact, though they may improve maintainability.

❓ Question — Clarification Requests

❓ (Question mark) signals a question—a genuine query about intent or unclear logic. Unlike other prefixes, this is not a directive to change code but a request for clarification from the author.

How caveman-review Generates Severity Prefixes

When the caveman-review command executes, it analyzes the diff and classifies each finding according to the schema documented in src/plugins/opencode/commands/caveman-review.md at line 7. The output follows a standardized format that places the emoji immediately after the line reference:

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

Concrete examples from the documentation include:

L42: 🔴 bug: user can be null after .find(). Add guard before .email.
L88‑140: 🔵 nit: 50‑line fn does 4 things. Extract validate/normalize/persist.
L23: 🟡 risk: no retry on 429. Wrap in withBackoff(3).
L107: ❓ q: why drop the cache here?

Parsing caveman-review Output Programmatically

You can consume these severity prefixes programmatically to route findings to appropriate handlers. The emojis map to the lowercase severity strings defined in skills/caveman-review/SKILL.md.

import { parseReview } from '@caveman/review-utils';

// Suppose `output` is the raw string from `caveman review`
const findings = parseReview(output);

findings.forEach(f => {
  switch (f.severity) {
    case 'bug':   handleCritical(f); break;   // 🔴
    case 'risk':  handleRisk(f); break;       // 🟡
    case 'nit':   handleNitpick(f); break;    // 🔵
    case 'question': askAuthor(f); break;     // ❓
  }
});

Source Files Defining Severity Prefixes

The severity prefix system is distributed across several files in the JuliusBrussee/caveman repository:

• skills/caveman-review/SKILL.md (lines 17‑20): Canonical definitions of bug, risk, nit, and question.
• skills/caveman-review/README.md (lines 7‑9): Overview of the comment format and severity meanings.
• src/plugins/opencode/commands/caveman-review.md (line 7): Documentation of the command output format and emoji placement.
• README.md (line 143): Brief emoji legend in the root documentation.

Summary

• 🔴 bug indicates critical defects that must be fixed immediately to prevent incidents.
• 🟡 risk flags fragile code that works now but could cause future failures.
• 🔵 nit marks optional style, naming, or micro-optimization improvements.
• ❓ question requests clarification on intent rather than prescribing changes.
• Definitions reside in skills/caveman-review/SKILL.md and the format is enforced by the command implementation in src/plugins/opencode/commands/caveman-review.md.

Frequently Asked Questions

What is the difference between 🔴 bug and 🟡 risk in caveman-review?

A 🔴 bug represents definitively broken behavior that will cause an error or incident, while a 🟡 risk indicates code that functions correctly but contains fragility—such as missing null checks or lack of retry logic—that could fail under specific conditions or future changes.

Can I disable 🔵 nit comments in caveman-review output?

The severity prefixes are fixed classifications hardcoded into the review format. While you cannot disable generation at the source, you can filter the output programmatically by checking for the nit severity string or 🔵 emoji when parsing results.

Where are the severity emoji definitions stored in the caveman repository?

The canonical definitions are located in skills/caveman-review/SKILL.md at lines 17‑20, with supplementary documentation in skills/caveman-review/README.md and the command reference at src/plugins/opencode/commands/caveman-review.md.

Does the ❓ question prefix require action from the author?

Unlike 🔴, 🟡, or 🔵, the ❓ question prefix is not a directive to modify code but a request for explanation. Authors should respond to clarify intent, but no code change is strictly required unless the discussion reveals an underlying issue.

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