what — explain the concepts, not the timeline

A session ends. The work is done and the summary is accurate, and you still cannot review the next PR in that area, because eight of the nouns were new. That gap does not close by re-reading the summary. It closes by someone naming the eight nouns and defining them.

Nothing else in the stack does this. Bridge (P1) records what happened. /handoff writes state for the next agent. /comprehend runs a multi-stage teach-to-mastery loop. /what is the fast one: the vocabulary of the last stretch of work, explained once, grounded in where it actually appeared.

The one rule

Concepts, not chronology.

If the answer reads "first I did X, then Y, then Z", it is a session log and it has failed. /what is organised by idea, ranked by what blocks understanding — never by what was hardest to build or said most often.

Scope

/what explains everything since you last asked /what. One rule covers both cases:

The re-pitch case. When the slice is short or plain, the script returns an empty inventory. That is not a failure — it is the signal to do what wait-what does: say the last message again, with more context, shorter sentences, and the workspace's own words. Do not report "no concepts found."

Procedure

1. Build the inventory (deterministic — never do this by eye)

Run it from the project you are explaining, with an absolute path to the script — transcript, catalog and CLAUDE.md resolution all key off the current directory, so cd-ing into the skill dir to shorten the path breaks resolution.

W=~/.claude/skills/what/scripts/what_concepts.py

python3 $W --json                      # since the last /what, current project
python3 $W --scope session --json      # whole session, markers ignored
python3 $W --conversation docs/conversations/<id>.md
python3 $W --cwd /path/to/other/repo   # explain a session from elsewhere

Useful when the default filters misjudge a term: --keep-term MAJOR forces a stoplisted term back in, --stopword <t> drops one, --include-tools also mines the code the agent wrote, --top N / --min-freq N move the thresholds.

It resolves the transcript, extracts candidate terms from the agent's prose, and returns each one with four facts that decide the explanation:

• uses — how load-bearing the term was.
• agent_introduced — the human never used this word. High-value: you brought it, so you owe the definition.
• defined_inline — already glossed in-session. If yes, do not re-explain it; reference it.
• coverage — grounded (an entity page exists; read it), partial, ungrounded (nothing — a Bookkeeping (P6) candidate).

Ranking is deliberately not frequency-first. A term said 200 times and already defined ranks below a term said twice and never defined.

Generic compounds (audit-time, cache-first, dev-like) are demoted, not removed. A filter there could only ever fire on ungrounded terms — the un-filed coinages this skill exists to surface — so it would delete its own highest-value rows. threat-model and sell-side still appear; they just sit below real coinages.

--include-tools answers a different question. By default only the agent's prose is mined, because prose is what the operator actually read. Adding --include-tools also mines the code the agent wrote, which changes the question from "what did you say to me" to "what vocabulary is in the diff" — useful after a build-heavy session where the agent acted more than it spoke, but it surfaces identifiers and test-fixture strings alongside real concepts. Read it with that in mind; do not treat every snake_case row as a concept.

2. Read the grounded claims before writing a word

Every grounded row carries an entity path. Read those bodies. The knowledge graph already holds the workspace's own definition, and inventing a second one is how two vocabularies for one idea get created.

3. Explain, in rank order

Top rows first. Stop at the point where the remaining rows would not change what the operator can now do. Six well-explained concepts beat twelve listed.

4. Route the ungrounded terms through the P6 scoring gate

Every ungrounded row is a Bookkeeping (P6) candidate — not an entity. Measured precision on real sessions is roughly 1-2 genuine concepts per 12 rows, so filing the column wholesale would put ten junk pages per session into a graph whose contract is that it never holds unscored items (CLAUDE.md, Nous gate

= 5/9).

So: score first, file what clears the gate, report the rest.

# `score` reads a raw-extract FILE (there is no --content flag). Write the
# candidates out, score the file, file only what clears.
python3 ~/.claude/skills/bookkeeping/scripts/bookkeeping.py score --file <raw-extract.md> --verbose

If the gate reports LLM unavailable, keeping heuristic, it ran degraded — hold the candidates rather than filing on a heuristic-only score.

Filing is still a reflex, not a question — you do not ask permission to run the gate. What you never do is skip it.

The register

Borrowed from wait-what and made explicit. These are the rules the explanation is graded on:

1. One idea per sentence. Active voice. Under ~25 words.
2. Define on first use. No term from the inventory may appear in an explanation before its own definition.
3. Use the workspace's words. Bookkeeping (P6), not "the filing thing". Ubiquitous language comes from CLAUDE.md and the entity slugs — never invent a synonym for something that already has a name.
4. No enum names, no internal identifiers, no file paths as nouns. Those are anchors, not explanations. .control/policy.yaml is where a rule lives, not what the rule is.
5. Every concept gets a contrast. State the nearest thing it is confused with, and the difference. A definition without a boundary does not stick.
6. Every concept gets an anchor. Where it appeared in this session: file.py:120, a PR number, a commit. Ungrounded and unanchored is a vocabulary lesson, not a /what.
7. Say what you are unsure of. A term you used but cannot define is the most useful line in the answer.

Output shape

## The short version
Three sentences. No term from the inventory appears here.

## Concepts

### <Term> — <five-word gloss>
**What it is.** Two or three short sentences.
**Why it showed up.** <anchor: file:line / PR / commit>
**Not to be confused with.** <nearest neighbour, and the difference>
**Where it lives.** <entity path, or "not in the knowledge graph yet">

## Not in the knowledge graph yet
<terms filed as P6 candidates, with what was filed>

## If you remember one thing
One sentence.

Anti-rationalization

Composition

Validation (skill self-test)

A /what answer is well-formed iff:

• what_concepts.py was actually run, and the answer's concepts come from its top rows
• No section is ordered by time
• Every explained term has an anchor in this session
• Every grounded term's entity body was read before it was explained
• Every ungrounded term was scored via P6, and those clearing >= 5/9 were filed
• Each concept states what it is not
• The short version contains no term from the inventory

Script tests: python3 -m pytest scripts/test_what_concepts.py -v (114 tests).

The suite is held honest by a mutation proof: bash scripts/mutate.sh breaks the implementation 57 ways and requires the suite to catch all 57. Run it after any change to what_concepts.py. It asserts a clean tree first, because its revert-to-HEAD baseline would otherwise destroy uncommitted work on line one.

References

• scripts/what_concepts.py — the deterministic inventory + knowledge-graph coverage classifier.
• scripts/test_what_concepts.py — its unit suite (the step-3 skillify gate).
• scripts/mutate.sh — the mutation proof that keeps that suite honest.

A fixture-based precision gate was built alongside this suite over three rounds and then deleted. Cross-model review measured it catching strictly fewer degenerate implementations than the pytest suite it sat beside, while its own meta-properties — is the register padded, are the degenerates distinct, is the grading really absolute — failed review three times running. A second gate that is weaker than the first and harder to keep honest is not a gate; the mutation proof does that job.

• Prior art: mattpocock/skills productivity/wait-what — the terse mid-conversation re-pitch. /what keeps its two best ideas (pin the register, pin the vocabulary source) and adds session scope plus knowledge-graph grounding.