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

> Discover the meaning behind caveman-review tool's severity prefixes 🔴🟡🔵❓ Understand code review findings instantly with these emoji indicators for bugs, risks, nits, and questions.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: api-reference
- Published: 2026-07-13

---

**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`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-review/SKILL.md) at lines 17‑20, with additional context in [`skills/caveman-review/README.md`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-review/SKILL.md).

```javascript
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`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-review/SKILL.md)** (lines 17‑20): Canonical definitions of bug, risk, nit, and question.
- **[`skills/caveman-review/README.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-review/README.md)** (lines 7‑9): Overview of the comment format and severity meanings.
- **[`src/plugins/opencode/commands/caveman-review.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/commands/caveman-review.md)** (line 7): Documentation of the command output format and emoji placement.
- **[`README.md`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-review/SKILL.md) and the format is enforced by the command implementation in [`src/plugins/opencode/commands/caveman-review.md`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-review/SKILL.md) at lines 17‑20, with supplementary documentation in [`skills/caveman-review/README.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-review/README.md) and the command reference at [`src/plugins/opencode/commands/caveman-review.md`](https://github.com/JuliusBrussee/caveman/blob/main/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.