Why Caveman Skips Invented Abbreviations Like cfg/impl/req but Keeps Standard Acronyms Like DB/API/HTTP

Caveman prohibits invented abbreviations such as cfg, impl, and req because they consume the same number of tokens as full words while harming readability, whereas standard acronyms like DB, API, and HTTP are token-efficient and universally understood.

The JuliusBrussee/caveman repository enforces strict prompt-engineering guidelines that prioritize token efficiency and clarity. Understanding why Caveman skips invented abbreviations while allowing standard acronyms requires examining how modern tokenizers process text and where the rules are codified. This analysis breaks down the specific logic found in the project's skill definition files.

The Tokenization Logic Behind Caveman's Abbreviation Rules

Caveman's filtering logic targets token efficiency—the practice of minimizing the number of sub-word tokens that language models process. The rules distinguish between standard acronyms that compress meaning into single tokens and invented abbreviations that fail to reduce token count.

Why Standard Acronyms Pass (DB, API, HTTP)

Standard technical acronyms like DB, API, and HTTP remain acceptable because they are tokenized as single units. According to the source code in skills/caveman/SKILL.md, these terms are "widely recognized" and understood instantly by technical audiences, meaning no cognitive overhead is introduced while maintaining token efficiency.

Why Invented Abbreviations Fail (cfg, impl, req)

Custom shorthand such as cfg, impl, req, res, and fn triggers Caveman's filters because the tokenizer splits these strings into the same number of sub-tokens as their full-word equivalents. This yields zero token savings while forcing readers to decode non-standard terminology. The specification explicitly prohibits these invented forms because the full word is both cheaper (fewer or equal tokens) and clearer.

The Source of Truth in SKILL.md

The definitive rules reside in skills/caveman/SKILL.md, with a mirrored copy in plugins/caveman/skills/caveman/SKILL.md. The exact specification states:

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

This single rule encapsulates the tokenizer behavior and readability concerns that drive Caveman's filtering decisions.

Practical Examples: Before and After Processing

The following examples demonstrate how Caveman transforms text containing prohibited abbreviations versus standard acronyms.

An input containing invented abbreviations is flagged:

The cfg file contains the req parameters for the impl module.

Text using standard acronyms remains unchanged:

The DB query uses the HTTP API to fetch data.

After Caveman processing, the disallowed abbreviations expand to full words:

The configuration file contains the request parameters for the implementation module.

Summary

• Caveman permits standard acronyms (DB, API, HTTP) because they tokenize as single units and require no decoding by technical readers.
• Invented abbreviations (cfg, impl, req) are prohibited because they split into multiple tokens, offering zero efficiency gains while reducing clarity.
• The rules are codified in skills/caveman/SKILL.md and emphasize that full words are cheaper and clearer than custom shorthand.
• Always prefer complete words over non-standard abbreviations when writing for Caveman-compatible prompts.

Frequently Asked Questions

Why does Caveman care about token count?

Language models process text as discrete tokens, and fewer tokens generally mean lower latency and processing costs. Caveman optimizes for this by ensuring that every abbreviation actually reduces token count rather than merely obfuscating the text.

What happens if I use "fn" instead of "function"?

Caveman will strip or expand fn to function because the tokenizer splits "fn" into multiple sub-tokens that provide no savings over the full word, while introducing ambiguity about whether you mean "function" or something else.

Are all acronyms allowed, or only specific ones?

Only standard, well-known technical acronyms are permitted. The SKILL.md file specifically mentions DB, API, and HTTP as acceptable examples. Novel or domain-specific abbreviations that lack universal recognition are treated as invented abbreviations and disallowed.

Where can I find the complete ruleset?

The complete specification is located in skills/caveman/SKILL.md at the root of the repository, with an identical copy maintained in plugins/caveman/skills/caveman/SKILL.md for the plugin-based distribution.

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