Why Caveman Avoids Inventing New Abbreviations Like cfg, impl, and req

Caveman prohibits invented abbreviations such as cfg, impl, or req because modern tokenizers process them as identical token units to their full words, saving zero tokens while forcing readers to mentally decode unfamiliar shorthand.

The JuliusBrussee/caveman repository is an open-source agent compression framework designed to reduce spoken output token counts while maintaining complete technical accuracy. One of its core linguistic constraints, defined in the skill's manifest, explicitly rejects novel abbreviation creation in favor of full-word clarity.

The Rule Defined in skills/caveman/SKILL.md

The compression rules are codified in skills/caveman/SKILL.md at lines 21-22. The manifest explicitly states:

Standard well‑known tech acronyms OK (DB/API/HTTP); never invent new abbreviations (cfg/impl/req/res/fn) – tokenizer splits them the same as the full word: zero token saved, reader still decode. Full word cheaper AND clearer.

This directive forms the foundation of Caveman's text compression strategy. The skill processes user inputs according to these constraints, ensuring that even when users provide shorthand like cfg, the output remains the full token config.

Why Invented Abbreviations Provide Zero Benefit

Tokenizer Behavior and Token Parity

Modern subword tokenizers treat short invented abbreviations as independent tokens that consume the same token count as the words they replace. For example, cfg and configuration typically occupy identical token positions in LLM vocabularies. Swapping the full word for the abbreviation yields zero token reduction, rendering the compression effort meaningless according to the source code analysis.

Readability and Cognitive Load

Abbreviations that lack universal recognition introduce decoding overhead for readers. By preserving full words, Caveman maintains the 100% technical accuracy guarantee documented in README.md at lines 43-45. Clear, unabbreviated text requires less mental processing than deciphering context-dependent shorthand like impl (implementation) or req (request/requirement).

Multilingual Consistency

Caveman operates as a language-agnostic compression engine, handling English, Portuguese, Spanish, and even Classical Chinese (wenyan). Invented abbreviations vary across languages and would break this universal consistency. Full words provide stable, recognizable anchors regardless of the target language.

Algorithm Simplicity

The compression algorithm follows a minimal rule set: drop filler words (a/an/the, just/really/basically), shorten phrasing, and preserve code unchanged. Adding a dynamic abbreviation layer would significantly complicate the prompt logic without delivering measurable token savings.

Permitted Abbreviations vs. Prohibited Shorthand

Caveman distinguishes between standard tech acronyms and invented abbreviations:

• Allowed: DB, API, HTTP, URL — universally recognized industry standards
• Prohibited: cfg, impl, req, res, fn — non-standard shorthand that saves no tokens

This distinction ensures that compression only targets linguistic filler rather than semantic content.

Implementation Example

The following excerpt from skills/caveman/SKILL.md demonstrates the rule structure:

## Rules

Drop: articles (a/an/the), filler (just/really/basically/actually/simply), …
Standard well‑known tech acronyms OK (DB/API/HTTP); **never invent new abbreviations (cfg/impl/req/res/fn)** — tokenizer split them same as full word: zero token saved, reader still decode. Full word cheaper **AND** clearer.

When processing code, Caveman maintains full token names:

// Input with invented abbreviation
const cfg = loadConfig();

// Caveman output (unchanged, full word preserved)
const config = loadConfig();

Even if the user writes cfg, the skill does not auto-replace it with a shorter form, as the tokenizer would process both variants identically.

Summary

• Token parity: Abbreviations like cfg and config consume identical token counts, offering no compression benefit.
• Clarity priority: Full words eliminate cognitive decoding overhead and maintain 100% technical accuracy as specified in README.md.
• Standard acronyms only: Only universally recognized forms like API or HTTP are permitted; invented shorthand like impl or req is explicitly banned.
• Language agnostic: The policy supports multilingual consistency across English, Portuguese, Spanish, and Classical Chinese without language-specific abbreviation tables.
• Simple rules: The compression algorithm avoids complex abbreviation dictionaries, focusing instead on removing filler words and shortening phrases.

Frequently Asked Questions

Why doesn't Caveman abbreviate "configuration" to "cfg"?

Modern tokenizers split cfg into the same number of tokens as configuration, meaning no tokens are saved. Additionally, cfg requires readers to mentally expand the abbreviation, whereas the full word is immediately comprehensible. According to the skills/caveman/SKILL.md rules, invented abbreviations provide "zero token saved, reader still decode."

Are there any exceptions to the abbreviation rule?

Only standard, well-known tech acronyms are permitted. These include DB, API, HTTP, URL, and similar industry-standard terms that predate the specific codebase. Any project-specific or ad-hoc abbreviation like req for request or impl for implementation violates the compression rules at lines 21-22 of the skill manifest.

How does this policy affect non-English languages?

The policy strengthens multilingual support. Since Caveman handles English, Portuguese, Spanish, and Classical Chinese (wenyan), invented English abbreviations would create inconsistency across languages. Full words provide stable reference points regardless of the output language, ensuring the compression rules remain universally applicable without language-specific abbreviation dictionaries.

Where are these compression rules defined?

The primary rules are documented in skills/caveman/SKILL.md at lines 21-22, with additional context about technical accuracy guarantees in README.md at lines 43-45. The AGENTS.md file indicates that sub-agents like cavecrew-reviewer inherit these same compression constraints, ensuring consistent behavior across the entire JuliusBrussee/caveman ecosystem.

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