# How the cavecrew-reviewer Agent Indicates Severity of Findings in Caveman

> Understand how the cavecrew-reviewer agent signals finding severity with its four-tier emoji system. Easily scan bug, risk, nit, and question indicators.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: how-to-guide
- Published: 2026-08-22

---

**The cavecrew-reviewer agent uses a four-tier emoji system (🔴 bug, 🟡 risk, 🔵 nit, ❓ question) to prefix each finding, making severity instantly scannable in one-line audit outputs.**

The **cavecrew-reviewer** is a specialized sub-agent in the [JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman) repository designed to audit diffs, branches, or single files. When analyzing code, it encodes the **severity of findings** directly into its output using standardized emojis and tier labels defined in the agent's front-matter configuration.

## The Four-Tier Severity System

The severity mappings are declared in [`agents/cavecrew-reviewer.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-reviewer.md) under the **"Severity"** section, with an identical copy maintained at [`plugins/caveman/agents/cavecrew-reviewer.md`](https://github.com/JuliusBrussee/caveman/blob/main/plugins/caveman/agents/cavecrew-reviewer.md). Each tier combines a visual emoji with a textual label for both human readability and machine parsing.

### 🔴 Bug (Critical Issues)

The **red circle** emoji indicates critical defects that affect correctness or security. Use this tier for wrong output, crashes, security holes, and data loss scenarios.

Example output:

```text
src/auth.ts:108: 🔴 bug: token expiry uses "<" not "<=". Off-by-one allows expired tokens 1 tick.

```

### 🟡 Risk (Potential Problems)

The **yellow circle** emoji flags edge cases, race conditions, resource leaks, performance cliffs, and missing guard clauses. These issues may not fail immediately but represent latent defects.

Example output:

```text
src/db.js:77: 🟡 risk: pool not closed on error path. Add try/finally.

```

### 🔵 Nit (Style and Polish)

The **blue circle** emoji covers style violations, naming inconsistencies, and micro-performance optimizations. **Important:** The `cavecrew-reviewer` agent emits nit-level findings only when the user explicitly requests a thorough review.

### ❓ Question (Needs Clarification)

The **question mark** emoji prefixes items requiring author intent before the agent can judge severity. Use this when the code logic is ambiguous or contradicts apparent conventions.

Example output:

```text
utils/helpers.ts:12: ❓ question: why duplicate .trim() here?

```

## Output Format and Structure

The `cavecrew-reviewer` agent follows a strict one-line format for each finding:

```text
path/to/file.ts:42: <emoji> <tier>: <problem>. <fix>.

```

After listing individual findings, the agent outputs a **totals line** that aggregates counts by severity:

```text
totals: 1🔴 1🟡 1❓

```

If no issues are detected, the agent returns a simple confirmation:

```text
No issues.

```

## Configuration in Source Files

The severity table is hardcoded in the agent definition files:

- **[`agents/cavecrew-reviewer.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-reviewer.md)** – Core agent definition containing the severity table (lines 14-22)
- **[`plugins/caveman/agents/cavecrew-reviewer.md`](https://github.com/JuliusBrussee/caveman/blob/main/plugins/caveman/agents/cavecrew-reviewer.md)** – Plugin-system copy with identical severity mappings
- **[`skills/cavecrew/README.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/cavecrew/README.md)** – User-facing documentation summarizing the emoji system
- **[`skills/cavecrew/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/cavecrew/SKILL.md)** – Command reference for the `cavecrew-reviewer` skill

According to the [source code](https://github.com/JuliusBrussee/caveman/blob/main/plugins/caveman/agents/cavecrew-reviewer.md), the severity definitions appear in the front-matter YAML block, ensuring consistent interpretation across CLI and programmatic invocations.

## Parsing Severity Programmatically

You can consume `cavecrew-reviewer` output in automation scripts by mapping emojis to severity strings:

```javascript
const severityMap = {
  '🔴': 'bug',
  '🟡': 'risk',
  '🔵': 'nit',
  '❓': 'question',
};

function parseFinding(line) {
  const match = line.match(/^([^:]+):(\d+): (\S) (\w+): (.+)$/);
  if (!match) return null;
  
  const [, file, lineNo, emoji, tier, description] = match;
  return {
    file,
    line: Number(lineNo),
    severity: severityMap[emoji],
    tier,
    description
  };
}

// Example usage
const finding = parseFinding('src/auth.ts:42: 🔴 bug: token expiry uses "<" not "<=".');
console.log(finding);
// { file: 'src/auth.ts', line: 42, severity: 'bug', tier: 'bug', description: 'token expiry uses "<" not "<=".' }

```

To invoke the reviewer via the Caveman CLI:

```bash
caveman-reviewer --diff HEAD~1..HEAD

```

## Summary

- The **cavecrew-reviewer agent** employs four severity tiers encoded as emojis: **🔴 bug**, **🟡 risk**, **🔵 nit**, and **❓ question**.
- Severity definitions reside in [`agents/cavecrew-reviewer.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-reviewer.md) and [`plugins/caveman/agents/cavecrew-reviewer.md`](https://github.com/JuliusBrussee/caveman/blob/main/plugins/caveman/agents/cavecrew-reviewer.md).
- Output format combines file paths, line numbers, emojis, and tier labels for immediate visual parsing.
- The **totals line** aggregates findings by emoji count for quick assessment.
- **Nit-level findings** require explicit activation through thorough review mode.

## Frequently Asked Questions

### What do the emojis in cavecrew-reviewer output mean?

The emojis represent four distinct severity levels: 🔴 indicates a **bug** (critical failure), 🟡 indicates a **risk** (potential issue), 🔵 indicates a **nit** (style concern), and ❓ indicates a **question** (needs clarification). These mappings are defined in the agent's front-matter configuration file.

### How do I enable nit-level findings in cavecrew-reviewer?

Nit-level findings (🔵) are emitted only when you explicitly request a **thorough review** mode. By default, the `cavecrew-reviewer` agent suppresses style and micro-performance suggestions to reduce noise. Check the Caveman CLI documentation for the specific flag to enable comprehensive auditing.

### Where is the severity table defined for the cavecrew-reviewer agent?

The severity table is defined in the agent's markdown front-matter at [`agents/cavecrew-reviewer.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-reviewer.md) (lines 14-22), with a duplicate maintained at [`plugins/caveman/agents/cavecrew-reviewer.md`](https://github.com/JuliusBrussee/caveman/blob/main/plugins/caveman/agents/cavecrew-reviewer.md) for the plugin system. The table maps each emoji to its corresponding tier label and usage criteria.

### Can I parse cavecrew-reviewer output automatically in CI/CD?

Yes. The one-line format (`file:line: emoji tier: description`) and the predictable totals line make the output suitable for regex parsing in CI pipelines. Map the Unicode emojis to severity strings in your automation scripts, or grep for specific tiers (e.g., `🔴 bug`) to fail builds on critical issues while allowing risks to pass with warnings.