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

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. 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:

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).
• 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. 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, 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. 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 to accommodate additional fix attempts.

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