# What Happens When caveman-compress Hits a Retry Failure After 2 Attempts

> Discover what caveman-compress does after two retry failures. Learn how it restores original files and signals compression failure.

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

---

**When caveman-compress fails validation after two attempts, it restores the original file from backup, deletes the temporary backup, and returns `False` to signal unsuccessful compression.**

The `caveman-compress` skill in the JuliusBrussee/caveman repository automates file compression through Claude API calls, but includes a robust validation and retry mechanism to ensure output quality. When validation fails repeatedly, the system implements a complete rollback strategy rather than leaving corrupted files in place. Understanding this **caveman-compress retry failure** behavior is crucial for debugging compression workflows and handling edge cases in your documentation pipeline.

## The Validation Retry Mechanism in caveman-compress

The compression workflow is governed by a constant `MAX_RETRIES` set to **2**, defined at line 16 of [`skills/caveman-compress/scripts/compress.py`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/scripts/compress.py). This limit controls how many times the system attempts to validate and fix the compressed output before giving up.

The process creates a backup of the original file before any modifications, then enters a loop that alternates between validation and corrective prompting. According to the source code, the validation step relies on the **caveman-validate** skill to check the compressed output against project-specific rules.

## Step-by-Step: How the Two-Attempt Loop Works

### Attempt 1: Initial Validation and Error Reporting

During the first iteration (`attempt == 0`), `caveman-compress` calls the `validate` function on the backup and newly-compressed file. If `result.is_valid` returns `True`, the function exits immediately and returns `True` to indicate success.

If validation fails, the system prints all validation errors and proceeds to a fix attempt. Since `attempt` is not the final allowed attempt, `caveman-compress` generates a fix prompt using `build_fix_prompt` and sends it to Claude. The corrected output is written back to the target file.

### Attempt 2: Fix Prompt and Final Validation

The second iteration (`attempt == 1`) runs the same validation logic against the corrected content. If validation succeeds, the function returns `True` and the compressed file persists. If validation fails again, the loop reaches the terminal condition where `attempt == MAX_RETRIES - 1`.

## The Final Rollback: What Happens After the Second Failure

When the second validation attempt fails, `caveman-compress` executes a complete rollback to prevent data loss:

1. **File Restoration**: The original content is restored using `filepath.write_text(original_text)`, overwriting the failed compression attempt with the backup content.
2. **Cleanup**: The temporary backup file is removed via `backup_path.unlink(missing_ok=True)`.
3. **Failure Signal**: The system prints "❌ Failed after retries — original restored" and the `compress_file` function returns `False`.

This ensures that no partially-compressed or corrupted files remain in the workspace, leaving the source file exactly as it was before the compression attempt began.

## Implementing the Compress Workflow in Your Code

You can invoke the compression logic directly from Python to handle retry failures programmatically:

```python
from pathlib import Path
from skills.caveman_compress.scripts.compress import compress_file

# Attempt to compress a markdown file

result = compress_file(Path("docs/guide.md"))

if result:
    print("✅ Compression succeeded")
else:
    print("⚠️ Compression failed – original file restored")

```

Running this script on a file that repeatedly violates validation rules—such as missing required headings after Claude's attempted fix—will trigger the rollback behavior described above, preserving your original documentation while signaling the failure through the boolean return value.

## Summary

- **caveman-compress** allows exactly **2 validation attempts** (defined by `MAX_RETRIES` in [`skills/caveman-compress/scripts/compress.py`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/scripts/compress.py)).
- After the first failure, the system automatically requests fixes from Claude using `build_fix_prompt` and rewrites the file.
- Upon the second failure, the function restores the original file content, deletes the backup, and returns `False`.
- The rollback mechanism ensures atomicity—files are either successfully compressed or returned to their original state.

## Frequently Asked Questions

### How many retry attempts does caveman-compress allow before failing?

The system allows **2 attempts** total. This is controlled by the `MAX_RETRIES` constant set to `2` at line 16 of [`skills/caveman-compress/scripts/compress.py`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/scripts/compress.py). The loop runs for attempt indices 0 and 1, and fails permanently if the second attempt does not pass validation.

### Where does caveman-compress store the backup file during compression?

The backup is stored in the same directory as the target file, created as a temporary copy before any compression begins. The specific backup path handling is implemented in [`compress.py`](https://github.com/JuliusBrussee/caveman/blob/main/compress.py), and the file is automatically deleted via `backup_path.unlink(missing_ok=True)` after either successful compression or a retry failure.

### What happens to the original file if both validation attempts fail?

The original file is **completely restored** to its pre-compression state. The function calls `filepath.write_text(original_text)` to overwrite any failed compression attempts, ensuring the source file remains intact and unmodified.

### Can I adjust the number of retry attempts in caveman-compress?

Currently, the retry limit is hardcoded as `MAX_RETRIES = 2` in [`skills/caveman-compress/scripts/compress.py`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/scripts/compress.py). To change this behavior, you would need to modify the source constant and potentially adjust the validation logic in [`skills/caveman-validate/scripts/validate.py`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-validate/scripts/validate.py) to accommodate additional fix attempts.