# cavecrew-reviewer Output Format and Sorting Rules in Caveman

> Discover the cavecrew-reviewer output format and sorting rules for clear, concise findings. Learn how findings are sorted alphabetically by file and numerically by line number.

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

---

**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`](https://github.com/JuliusBrussee/caveman/blob/main/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:

```text
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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/src/api/auth.ts), line 42 precedes line 118.

## Zero-Issue Response

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

```text
No issues.

```

## Practical Examples

Review output demonstrating the format and sorting:

```text
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`](https://github.com/JuliusBrussee/caveman/blob/main/src/api/auth.ts) appears before [`src/utils.ts`](https://github.com/JuliusBrussee/caveman/blob/main/src/utils.ts) alphabetically, and lines 42 and 118 are in ascending order.

Implementation pseudocode for generating compliant output:

```javascript
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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-reviewer.md), with usage notes in [`skills/cavecrew/README.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/cavecrew/README.md) and agent listings in [`AGENTS.md`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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.