cavecrew-reviewer Output Format and Sorting Rules in Caveman

TLDR: The cavecrew-reviewer outputs one-line findings in the strict format path/to/file.ext:<line-number>: <emoji> <severity>: <problem>. <fix>., sorted alphabetically by file path then numerically by line number.

The cavecrew-reviewer is a diff/branch/file reviewer agent in the JuliusBrussee/caveman repository that enforces a deterministic one-line output format for code reviews. According to the agent definition in agents/cavecrew-reviewer.md (lines 4-6), each finding must include a specific severity emoji and follow a precise template to ensure machine-parseable results.

Strict One-Line Output Format

Each finding generated by cavecrew-reviewer must adhere to this exact single-line structure:

path/to/file.ext:<line-number>: <emoji> <severity>: <problem>. <fix>.

The format requires six components separated by specific delimiters:

• File path: Relative path to the source file (e.g., src/api/auth.ts)
• Line number: Integer indicating the specific line (e.g., 42)
• Emoji: Visual severity indicator from the approved set
• Severity label: Text classification (bug, risk, nit, or question)
• Problem description: Brief explanation ending with a period
• Suggested fix: Recommended solution ending with a period

Severity Levels and Emojis

As defined in agents/cavecrew-reviewer.md (lines 24-30), the reviewer uses four severity tiers:

Emoji	Severity	Use Case
🔴	bug	Wrong output, crashes, security holes, data loss
🟡	risk	Edge cases, race conditions, resource leaks, performance cliffs
🔵	nit	Style issues, naming conventions, micro-optimizations (emitted only during thorough reviews)
❓	question	Requires author intent before judgment

How cavecrew-reviewer Sorts Findings

Findings are ordered first by file path alphabetically, then by line number in ascending order within each file. This deterministic sorting rule, specified in agents/cavecrew-reviewer.md (lines 33-34), ensures consistent output across review runs and makes comparisons easy.

For example, src/api/auth.ts:42 appears before src/utils.ts:7 due to alphabetical file ordering. Within src/api/auth.ts, line 42 precedes line 118.

Zero-Issue Response

When no issues are detected, cavecrew-reviewer returns exactly this string:

No issues.

Practical Examples

Review output demonstrating the format and sorting:

src/api/auth.ts:42: 🔴 bug: token expiry uses "<" not "<=". Off-by-one allows expired tokens 1 tick.
src/api/auth.ts:118: 🟡 risk: pool not closed on error path. Add "try/finally".
src/utils.ts:7: ❓ question: why duplicate `.trim()` here?
totals: 1🔴 1🟡 1❓

Note that src/api/auth.ts appears before src/utils.ts alphabetically, and lines 42 and 118 are in ascending order.

Implementation pseudocode for generating compliant output:

function formatFinding(file, line, emoji, severity, problem, fix) {
  return `${file}:${line}: ${emoji} ${severity}: ${problem}. ${fix}.`;
}

// Generate a finding
const finding = formatFinding(
  'src/api/auth.ts', 
  42, 
  '🔴', 
  'bug',
  'token expiry uses "<" not "<="',
  'use "<=" to include the expiry tick'
);
console.log(finding);
// Output: src/api/auth.ts:42: 🔴 bug: token expiry uses "<" not "<=". use "<=" to include the expiry tick.

Summary

• Single-line format: path/file.ext:<line>: <emoji> <severity>: <problem>. <fix>.
• Four severity levels: 🔴 bug, 🟡 risk, 🔵 nit, ❓ question defined in agents/cavecrew-reviewer.md
• Sorting: Alphabetical by file path, then ascending by line number
• Empty state: Returns exactly No issues.
• Source files: Configuration lives in agents/cavecrew-reviewer.md, with usage notes in skills/cavecrew/README.md and agent listings in AGENTS.md

Frequently Asked Questions

What is the exact output format for cavecrew-reviewer findings?

Each finding follows the template path/to/file.ext:<line-number>: <emoji> <severity>: <problem>. <fix>. as defined in agents/cavecrew-reviewer.md. The format requires a file path, line number, severity emoji, severity label, problem description, and suggested fix, each separated by specific punctuation.

How does cavecrew-reviewer sort multiple findings?

Findings are sorted first by file path in alphabetical order, then by line number in ascending numeric order within each file. This deterministic ordering makes outputs comparable across different review runs.

What severity levels does cavecrew-reviewer support?

The tool supports four severity levels: 🔴 bug for critical issues, 🟡 risk for potential problems, 🔵 nit for style issues, and ❓ question for uncertain intent. Each maps to a specific emoji and use case as documented in the agent definition.

What does cavecrew-reviewer output when no issues are found?

When no issues are detected, the reviewer outputs exactly the string No issues. on a single line, with no additional formatting or content.

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