# How Caveman Handles Auto-Clarity When Compression Causes Ambiguity

> Discover how Caveman's auto-clarity ensures clarity by disabling aggressive compression when output risks ambiguity, keeping important messages secure.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: deep-dive
- Published: 2026-07-08

---

**Caveman's auto-clarity feature automatically disables aggressive compression when terse output risks ambiguity, temporarily restoring full prose for security warnings, irreversible actions, and confused user scenarios.**

The `JuliusBrussee/caveman` repository implements a novel compression mode that reduces LLM responses to terse "caveman" speech. To prevent dangerous misinterpretation, the system employs an **auto-clarity** safeguard that temporarily restores normal verbosity whenever critical context demands precision.

## How Auto-Clarity Detects Ambiguity Risks

The auto-clarity rule-set operates as a runtime safety-net within the `caveman-activate` hook. According to the human-readable documentation in [`skills/caveman/README.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/README.md), the system drops compression for "security warnings, irreversible-action confirmations, multi-step sequences where fragment ambiguity risks mis-read, and when the user repeats a question." The machine-readable rule in [`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md) reinforces this: "Auto-Clarity: drop caveman for security warnings, irreversible actions, user confused."

### Security Warnings and Irreversible Actions

When the model generates content involving **security warnings** or **irreversible-action confirmations**, the hook prioritizes clarity over brevity. For example, a message like "Deleting this repository cannot be undone" triggers auto-clarity because ambiguity could hide critical risk. Similarly, confirmation prompts such as "Are you sure you want to purge all data?" bypass compression to ensure the user clearly sees the consequence.

### Complex Multi-Step Sequences

**Multi-step sequences** where short fragments could be mis-ordered or lose context also trigger the safeguard. The hook detects when the model is about to emit chained instructions that might become unclear if compressed, preventing the emission of ambiguous step chains that could lead to user error.

### Repeated User Queries

When the user **repeats a question**, the system interprets this as a signal that the previous terse reply was not understood. The `caveman-activate` hook treats repetition as a confusion indicator, automatically switching to plain prose for the subsequent response to improve comprehension.

## The Caveman-Activate Hook Implementation

The enforcement logic resides in [`src/hooks/caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-activate.js), which intercepts model output before the compression stage. The hook evaluates incoming messages against the auto-clarity conditions using an internal check function.

When processing a response, the runtime executes logic similar to the following:

```javascript
// Simplified flow from src/hooks/caveman-activate.js
if (autoClarityNeeded(message)) {
  // Bypass compress()
  sendPlainProse(message);
} else {
  const {compressed} = compress(message);
  sendCompressed(compressed);
}

```

If `autoClarityNeeded()` returns true, the hook **drops the caveman mode** and calls `sendPlainProse()` to deliver the full-sentence output. Once the critical segment concludes—after the security warning block, confirmation dialog, or multi-step instruction—the runtime **re-enables the caveman compressor** seamlessly for subsequent output. This toggle happens automatically without requiring manual mode management from the client.

## Code Example: Auto-Clarity in Practice

The following interaction demonstrates how the system behaves when a user requests an irreversible action while in ultra-compression mode:

```markdown

# User request

/caveman ultra
Delete the entire repository now.

# Caveman response (auto-clarity triggers for irreversible action)

Sure, deleting a repository is **irreversible**.  
Do you really want to continue?

# User confirms

yes

# Caveman resumes ultra-compression for remaining output

Repo deletion queued. …

```

The mode switch occurs transparently. The user sees normal prose for the confirmation dialog, then the system automatically resumes aggressive compression for the final status message once the ambiguity risk passes.

## Summary

- **Auto-clarity** is a safety mechanism in `JuliusBrussee/caveman` that temporarily disables compression when ambiguity could cause harm.
- The **caveman-activate hook** checks for four conditions: security warnings, irreversible actions, complex multi-step sequences, and repeated user queries.
- When triggered, the hook **bypasses the `compress()` function** and calls `sendPlainProse()` instead, preserving full sentence structure.
- Compression **automatically resumes** after the critical segment ends, maintaining seamless user experience without manual intervention.
- Configuration and rules are defined in [`skills/caveman/README.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/README.md) and [`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md).

## Frequently Asked Questions

### What is Caveman auto-clarity?

Auto-clarity is a runtime safeguard implemented in the `caveman-activate` hook that temporarily disables the caveman compression mode whenever terse output risks misinterpretation. It ensures that critical information—such as security warnings or confirmation prompts—remains fully readable and unambiguous.

### When does Caveman disable compression?

The system disables compression when `autoClarityNeeded()` detects specific risk patterns: **security warnings**, **irreversible-action confirmations**, **multi-step sequences** where fragment order matters, and **repeated user questions** indicating confusion. These rules are defined in [`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md).

### Where is the auto-clarity logic implemented?

The implementation spans three key files: the human-readable description in [`skills/caveman/README.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/README.md), the machine-readable rules in [`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md), and the execution logic in [`src/hooks/caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-activate.js) which contains the `autoClarityNeeded()` check and the conditional bypass of the `compress()` function.

### How does Caveman resume compression after auto-clarity?

The `caveman-activate` hook tracks segment boundaries. Once the runtime finishes emitting the plain-prose block—whether a single warning message or a multi-step confirmation dialog—it automatically re-enables the compression pipeline for subsequent output. This transition is seamless and requires no user intervention.