caveman

SKILL.md

caveman — spec encoding

Applies to SPEC.md writes, spec-referencing prose, backprop entries.
Does NOT apply to code, error strings, commit messages, PR descriptions.

GRAMMAR

Drop articles (a, an, the).

Drop filler (just, really, basically, simply, actually).

Drop aux verbs where fragment works (is, are, was, were, being).

Drop pleasantries.

No hedging (skip "might", "perhaps", "could be worth").

Fragments fine.

Short synonyms: fix > implement, big > extensive, run > execute.

SYMBOLS

Prefer over words:
→   leads to / becomes / on <x>
∴   therefore / fix
∀   for all / every
∃   exists / some
!   must / required
?   may / optional / unknown
⊥   never / forbidden / nil
≠   not equal
∈   in
∉   not in
≤   at most
≥   at least
&   and
|   or
§   section reference

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.

SHAPES

Invariant:

V<n>: <subject> <relation> <condition>
V1: ∀ req → auth check before handler
V2: token expiry ≤ current_time → reject

Bug row (pipe table under §B):

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

Task row (pipe table under §T):

id|status|task|cites
T3|x|add auth mw|V1,I.api

Status: x done, ~ wip, . todo. Escape literal | as \|.

Interface:

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

EXAMPLES

Bad:

The system should ensure that every incoming request is properly authenticated before being forwarded to its corresponding handler function.

Good:

V1: ∀ req → auth check before handler

Bad:

We discovered that the token expiration check in the middleware was using a strict less-than comparison operator, which meant tokens were being rejected at the exact moment of their expiry.

Good:

B1: token < not ≤ → reject @ expiry boundary.

Bad:

The POST endpoint at /x accepts a JSON body and returns a 200 response with an object containing the created id.

Good:

api: POST /x → 200 {id}

BOUNDARIES

User asks for prose explanation → switch to normal English.

Spec documents for external review (RFC, pitch) → normal English.

Commit message → normal English (git readers expect it).

Diff comment in code → normal English.

WHEN UNSURE

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