When Does Caveman Automatically Drop Compression via Auto-Clarity?

Caveman automatically suspends its compressed caveman-style syntax when the auto-clarity system detects security warnings, irreversible operations, ambiguous command sequences, or explicit user requests for clarification, ensuring critical communications remain unambiguous.

The Caveman project (JuliusBrussee/caveman) implements a distinctive terse communication protocol that minimizes natural language into abbreviated, caveman-like expressions. While this compression reduces token usage, the repository includes an auto-clarity safety subsystem that intervenes when compression risks creating dangerous misunderstandings. According to the skill definition in skills/caveman/SKILL.md, auto-clarity temporarily drops caveman mode to prevent catastrophic misinterpretation during high-stakes interactions.

Five Triggers That Activate Auto-Clarity

The auto-clarity mechanism defined in skills/caveman/SKILL.md (lines 58-67) monitors for five specific conditions that mandate a temporary return to full clarity:

Security Warnings

When the system generates critical security alerts, auto-clarity ensures these messages remain fully comprehensible. Compressed caveman syntax could obscure threat severity or mitigation steps, so the system immediately drops compression for security-critical communications.

Irreversible Action Confirmations

Destructive operations such as dropping database tables or deleting permanent data trigger auto-clarity. The system requires explicit, unambiguous confirmation before executing actions that cannot be undone, suspending caveman mode to prevent accidental confirmation of catastrophic commands.

Ambiguous Multi-Step Sequences

Complex workflows involving multiple dependent steps activate auto-clarity when omitted conjunctions or fragmented ordering could confuse the execution sequence. If the compressed syntax risks reordering operations or creating logical gaps, the system temporarily expands to full syntax.

Technical Ambiguity from Compression

Auto-clarity engages when compression itself creates technical ambiguity. For example, the command migrate table drop column backup first loses critical ordering information without articles or conjunctions, potentially causing users to execute steps in the wrong sequence.

Explicit User Clarification Requests

When users ask for clarification, repeat questions, or indicate confusion, the system immediately drops caveman mode. This ensures that explanatory responses resolve rather than compound user uncertainty.

Source Code Implementation

The auto-clarity logic spans four critical files in the repository:

• skills/caveman/SKILL.md: Defines the five trigger conditions and auto-clarity behavior in the Auto-Clarity section (lines 58-67).
• src/hooks/caveman-mode-tracker.js: Handles slash-command activation and implements the detection logic that writes or clears the mode flag based on the triggers above.
• src/hooks/caveman-activate.js: Initializes Caveman mode at session start and maintains the persistent state that auto-clarity references when determining whether to resume compression.
• src/hooks/caveman-config.js: Resolves configuration defaults that influence auto-clarity sensitivity and engagement thresholds.

According to the source code, after the ambiguous or risky context is resolved, Caveman automatically resumes its compressed style without manual intervention.

Practical Code Examples

The following JavaScript examples demonstrate how auto-clarity behaves in different scenarios:

Destructive SQL Operation Trigger

// Security warning scenario - auto-clarity activates
console.log(`
⚠️ **Warning:** This will permanently delete all rows in the \`users\` table and cannot be undone.
DROP TABLE users;
`);
// Caveman response pauses terse style:
// > Caveman resume. Verify backup exists first.

Ambiguous Command Trigger

// Technical ambiguity - ordering unclear
runCommand('migrate table drop column backup first');
// Caveman response triggers clarification:
// > Drop column first? Clarify order: drop then backup, or backup then drop?

Normal Conversation (No Trigger)

// Standard operation - auto-clarity stays inactive
caveman.mode = 'full';
caveman.reply('Explain how caching works.');
// Compressed output continues:
// > Cache stores recent data for quick reuse. Avoid repeated fetches.

Summary

• Auto-clarity temporarily suspends caveman compression when safety-critical contexts are detected.
• The system triggers on five specific conditions: security warnings, irreversible actions, ambiguous multi-step sequences, technical compression ambiguity, and user clarification requests.
• Implementation resides in skills/caveman/SKILL.md and three hook files: caveman-mode-tracker.js, caveman-activate.js, and caveman-config.js.
• Compression automatically resumes after the risky context passes, requiring no manual reset.
• The feature prevents dangerous misinterpretations while maintaining the efficiency of caveman-style communication during routine interactions.

Frequently Asked Questions

Does auto-clarity permanently disable caveman mode?

No. Auto-clarity is a temporary suspension only. According to the implementation in src/hooks/caveman-mode-tracker.js, the system automatically restores caveman compression once the ambiguous or risky interaction concludes. The mode flag persists the original state and resumes without user intervention.

How does Caveman detect technical ambiguity in compressed commands?

The system parses command strings for ordering-dependent operations where removal of articles and conjunctions creates syntactic ambiguity. For example, migrate table drop column backup first lacks clear sequencing, triggering auto-clarity to request explicit ordering confirmation before execution.

Can users manually request auto-clarity?

Yes. While auto-clarity automatically engages for the five defined triggers, the system also responds to explicit user requests for clarification or repeated questions. When users indicate confusion or ask for expansion, the caveman-mode-tracker.js hook detects these signals and drops compression immediately.

Which file contains the auto-clarity trigger definitions?

The primary definitions reside in skills/caveman/SKILL.md at lines 58-67 in the Auto-Clarity section. This documentation specifies the exact conditions—security warnings, irreversible actions, multi-step ambiguity, technical compression issues, and clarification requests—that cause the system to drop caveman mode.

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