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

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 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 under the "Severity" section, with an identical copy maintained at 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:

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:

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:

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:

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

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

totals: 1🔴 1🟡 1❓

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

No issues.

Configuration in Source Files

The severity table is hardcoded in the agent definition files:

• agents/cavecrew-reviewer.md – Core agent definition containing the severity table (lines 14-22)
• plugins/caveman/agents/cavecrew-reviewer.md – Plugin-system copy with identical severity mappings
• skills/cavecrew/README.md – User-facing documentation summarizing the emoji system
• skills/cavecrew/SKILL.md – Command reference for the cavecrew-reviewer skill

According to the source code, 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:

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:

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 and 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 (lines 14-22), with a duplicate maintained at 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.

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