Caveman

caveman — spec-adjacent compression

Compressed English for plan artifacts. Saves tokens (loaded every invocation) and reads fast for both agent and human. Symbols unambiguous; grammar lean.

WHEN (self-trigger)

• Writing to a plan artifact: PRD.md, ARD.md, SPEC.md, PLAN.md, LESSONS.md, RESEARCH.md, CONTEXT.md.
• Writing spec-adjacent prose (invariants, bug rows, task rows, interface shapes).
• User says "caveman", "compress this", "be brief".

SCOPE

Apply caveman to: plan artifacts (listed above) + spec-adjacent prose.

Do NOT apply caveman to:

• Code (source files).
• Commit messages, PR descriptions, release notes.
• Diff comments in code.
• External-facing docs (RFC, pitch, customer-facing).
• User-facing explanations when the user asks for prose.
• Chat to the human in the terminal/shell (normal English; emoji allowed there for status/severity per the traffic-light palette below).

Caveman is compression, not amputation. If cutting a word loses a fact, keep it.

TOOLKIT

Apply in priority order. Grammar is the biggest token win. Symbols add density. Use words for anything obscure. 7 layers.

1. Grammar

• Drop articles (a, an, the).
• Drop filler (just, really, basically, simply, actually).
• Drop auxiliary verbs where fragments work (is, are, was, were, being).
• Drop hedging (might, perhaps, could be worth).
• Drop pleasantries.
• Use short synonyms: fix > implement, run > execute, big > extensive.
• Fragments are fine.

2. Programming operators (ligature-clean)

Prefer over words. ASCII so they survive in any artifact or commit.

3. RFC 2119 keywords (modality)

Use for requirement strength. These words are load-bearing — never compress them away.

4. Ranges & structure

Addressing: §<S>.<n> = section.item. §V.2 = invariants section, item 2. Commits, PRs, and chat all reference by §. Zero ambiguity.

5. Type (conventional-commit words)

Type is always a conventional-commit word — never an emoji. Works in artifacts, commits, and chat.

EMOJI — CHAT ONLY, NEVER IN ARTIFACTS

Emoji unicode is garbage in persisted artifacts (.md, code, commits, shell output). Artifacts use ASCII words. Chat to the human in the terminal/shell MAY use the fixed palette below for status/severity scanning.

6. Semantic emoji (chat-only, traffic-light palette)

Three circles for severity, one glyph for in-progress. Nothing else.

Forbidden (too many variants): 🟠 🟣 ⚫️ ⚪️ 🟤 and all square variants 🟥 🟧 🟨 🟩 🟦 🟪 ⬛️ ⬜️ 🟫. Also drop ✅ ❌ ⚠️ 🛑 from chat — redundant with the traffic-light circles. Keep ✓ / ✗ as artifact ASCII chars.

7. Directional emoji (chat-only, magnitude & trend)

Express change and trend — distinct from -> / => which express logical flow. Chat-only; artifacts use ASCII.

Reserved for navigation/sort only (sparingly, context-dependent): ◀️ ▶️ previous/next, 🔼 🔽 priority/sort up/down. Avoid ↖️ ↙️ ↕️ — too niche, use words.

TODO CHECKBOX (task lists only)

[x] / [ ] are reserved for task lists (complete/incomplete items). Never use them as general pass/fail status. Example — a PLAN.md task table:

id|status|task|cites
T1|[x]|scaffold repo|-
T2|[ ]|impl §I.api POST /x|V2
T3|[ ]|add §V.1 middleware|V1,I.api

For in-progress, mark [ ] and add a WIP flag in an adjacent cell, or use ~. Status values: [x] done, [ ] todo, ~ wip.

DROPPED (obscure math)

Dropped from earlier cavekit drafts. Use plain words instead — clearer for a non-always-technical reader.

If a word is clearer than a symbol, use the word.

PRESERVE VERBATIM

Never compress:

• Code blocks, snippets, one-liners with backticks.
• Paths: src/auth/mw.go.
• URLs.
• Identifiers: function names, variable names, env vars.
• Numbers and versions.
• Error message strings.
• SQL, regex, JSON, YAML.
• Quoted strings.

ARTIFACT vs CHAT — quick reference

BOUNDARIES

• User asks for a prose explanation → switch to normal English.
• Commit messages, PR descriptions → normal English.
• Diff comments in code → normal English.
• External-facing docs (RFC, pitch) → normal English.
• Artifacts (.md files, code, shell output) → no emoji; use ASCII equivalents.
• Chat to the human in terminal/shell → emoji OK for status/severity scanning.

SHAPES (toned — no math symbols)

Invariant (§V):

V<n>: <subject> <relation> <condition>
V1: MUST auth check every req before handler
V2: token expiry <= current_time => reject
V3: DB write MUST be in transaction

Bug row (pipe table under §B, owned by lessons):

id|date|cause|fix
B1|2026-04-20|token `<` not `<=`|V2

Task row (pipe table under §T, owned by plan; build flips status only):

id|status|task|cites
T1|[x]|scaffold repo|-
T2|[ ]|impl §I.api POST /x|V2
T3|~|add §V.1 middleware|V1,I.api

Status: [x] done, ~ wip, [ ] todo. Escape literal | as \|. Empty = -.

Interface (§I):

<kind>: <name> -> <shape>
api: POST /x -> 200 {id:string}
cmd: `foo bar <arg>` -> stdout JSON
env: FOO_KEY MUST be set

EXAMPLES

Bad (prose):

The authentication middleware must verify the token expiry on every request before allowing the handler to execute, and it must never log raw tokens.

Good (caveman):

V1: MUST check token expiry before handler && NEVER log raw tokens

Bad (prose):

We discovered that the token expiration check was using strict less-than, causing tokens to be rejected exactly at expiry.

Good (caveman):

fix B1: token < not <= => reject @ expiry boundary

Bad (prose):

Invariant 2 is violated at mw.go line 47; this is a critical bug and must be fixed before build.

Good (caveman):

FAIL V2 violated: mw.go:47. BLOCK B1. MUST fix before build.

Bad (prose):

A user has one or more orders, and an order may have zero or one coupon applied.

Good (caveman):

user 1..* orders; order 0..1 coupon?

Bad (chat with emoji in artifact):

## Status: ✅ all green, ⚠️ 1 warn

Good (artifact ASCII):

## Status: PASS all green, WARN 1

Good (chat to human):

🟢 all green, 🟡 1 warn

WHY CAVEMAN FOR ARTIFACTS

Artifacts are loaded every invocation. ~75% fewer tokens = ~75% fewer dollars and faster reads. Human skims fast too. Symbols are unambiguous across agent and reader. Math symbols were dropped because a non-always-technical reader stumbles on ∀/⊥; every/NEVER carry the same force with no learning curve.

WHEN UNSURE

If cutting a word loses a fact, keep it. Caveman is compression, not amputation. When the user asks for an explanation, switch to normal English. When the surface is a commit, PR, code comment, or external doc, use normal English.