mental-models

What this skill does

# Mental Models

The third knowledge boundary. `library-knowledge` caches a named thing's facts.
`specialist-knowledge` caches a domain's vertical craft. This caches **horizontal
systems insight** — transferable reframings that, applied to a renderer, a
parser, or a scheduler alike, *open classes of solution you did not know to look
for*. It is how the harness learns to tackle novel problems instead of
optimizing within the first class it thought of.

## The bootstrap paradox it solves
"You don't look for what you don't know" is logically closed — you cannot search
for a category you don't know exists. This skill attacks it from the two sides
that don't need foreknowledge of the answer:
1. **The gap makes the unknown visible.** Judged against a FLOOR (see
   spike-workflow), a far-from-floor result is an anomaly that *points at* a
   missing model — you don't need to already know the model to see the gap.
2. **The catalog turns each revealed gap into a future trigger.** Record the
   reframing and the SMELL that should fire it. Monotonically: unknown-unknown ->
   known-unknown (you hold the question) -> known-known (you hold the pattern).

The authority is the gap, not documentation. That is why this is learned from
surprise, not looked up by name.

## The store entry (the interface)
`mental-models.jsonl` at the repo root — one record per line, keyed by `smell`:
- `smell` — the symptom that should trigger the model ("this is slow", "O(n^2)
  nesting", "150K allocations", "complex state transitions", "deeply coupled").
- `reframe` — the question that opens classes ("is this allocation-bound or
  compute-bound?", "is there a data-oriented layout?").
- `solution_classes` — the classes the reframe reveals (not variants within one).
- `example` — a concrete instance (e.g. the Ghostty 75x-from-floor renderer).
- `taught_by_gap` — the gap that taught this model (provenance; the authority).
- `confirmed_on` — date.

## Workflow
- **Apply (cheap, common):** `models_lookup.py --smell "<symptom>"` (or `--all`)
  returns the matching reframing questions + solution classes BEFORE you commit
  to an approach. Used heavily by spike-workflow's class enumeration.
- **Learn (from a gap):** when a result sits far from its floor, or you discover
  post-hoc that a better class existed, record the model and its trigger:
  `models_record.py --smell "<symptom>" --from-json <file>`. (See
  `references/learning.md`.)

## Composition
- `spike-workflow` consults this during class enumeration and feeds it on every
  gap. The handshake is the learning loop.
- The reference-first FLOOR (spike-workflow / change_check.py --kind spike) is
  what makes gaps visible so there is something to learn from.
- The `knowledge-ratchet` governs graduation: a model leaned on repeatedly may be
  promoted into a convention, a lint, or a checklist item; a model only becomes
  its own skill on the VENDOR cost test.

## The one law here
A model here is domain-GENERAL reframing, not a fact (library-knowledge) and not
domain craft (specialist-knowledge). If it only applies to one library or one
platform, it belongs in those skills. Keep this shelf horizontal and transferable.

## Files
- `references/learning.md` — turning a gap into a recorded model.
- `scripts/store.py` — storage port (JSONL; only module touching disk).
- `scripts/models_lookup.py` — apply: smell -> reframing questions + classes.
- `scripts/models_record.py` — learn: record a model from a gap.