maximise-vocabulary

Maximise Vocabulary

Help a writer replace vague, verbose phrasing in their OWN text with precise words they choose themselves. The writer keeps their voice and learns the vocabulary; the tool never writes the final line.

The contract (IRON RULE)

Never rewrite the user's text. Surface precise candidates; the user picks and types the line.

Violating the letter of this rule violates its spirit. The whole point is that the writer improves, not that the output improves. Concretely:

• Diagnose and show. Do not produce the finished sentence.
• Corpus example sentences are shown verbatim — never edit, trim mid-claim, or paraphrase them.
• Definitions come from a real dictionary (WordNet), not your own paraphrase.
• Never invent a corpus occurrence, a usage sentence, or a count. If the corpus lacks a word, label it ◇ (your vocabulary), never ✓.

When to use / not

Use when: the writer pastes clumsy prose, asks for "the word for X", wants to de-scan, or wants to learn precise vocabulary while keeping their voice.

Do NOT use to: ghost-write, polish text the writer didn't ask about, or "improve" prose that is already precise.

Two modes

• Word mode (default, corpus-driven): a verbose phrase → a precise word. This is the sharp core.
• Sentence mode (diagnosis-driven): for run-ons / structure. Name the structural problem and the operation ("break into a list", "the main verb is buried", "you repeat X — cut one"). Never write the restructured sentence. The corpus can't hand back the user's own sentence without writing it, so this mode leans on diagnosis, not retrieval.

Procedure (per flagged chunk)

1. Scan the user's text; flag verbose/vague chunks. State what kind of imprecision (empty intensifier, vague verb, missing magnitude, unnamed scope, hedge, non-native construction).
2. Decompose the meaning. Find words whose denotation AND connotation cover the whole chunk. (This is why "wrangle" fits "manage LLMs through long disputes" — one verb carries both halves. Derive from meaning, never from a lookup keyed to the input.)
3. Source candidates from two places, label each:
   • ✓ corpus — attested in the corpus. Confirm with scripts/kwic.py (full text — NOT lex search, which only hits the distinctive-term index and silently drops ordinary words like "striving"). Show one verbatim sentence + source.
   • ◇ claude — your vocabulary, for words a finite corpus lacks (e.g. "wrangle" = 0 hits). Honest and allowed; just labelled.
4. Attach an official definition for each candidate via scripts/dict.py <word> --pos <pos> (WordNet). Pass the POS the word is used as — the first sense is often wrong (coax→coaxial cable). Pick the apt sense from the top few; show top 1–2 when senses differ meaningfully.
5. Emit a schema-valid cases.json and render it (see Blueprint). The user reads, picks, and types their own line.

Tools

Need	Command
Is a word in the corpus? + a verbatim sentence	python3 scripts/kwic.py "<word/phrase>" [--pool papers|blogs|all]
Official definition, POS-correct	uv run --with wn python scripts/dict.py <word> --pos verb|noun|adj|adv
Register / intent neighbours (secondary)	"$CLAUDE_PLUGIN_ROOT/bin/lex" search "<intent>" --json (see seshat:using-frontier-lexicon)

Blueprint (the output)

Data and presentation are split by a schema so the look is fixed and the content is verifiable:

• blueprint/schema.json — the contract a run must satisfy (validate with jsonschema).
• blueprint/cases.json — the data you emit (one object per flagged chunk; corpus candidates require corpus_count, usage, usage_source).
• blueprint/template.html — the renderer (Study Deck: per-word dictionary entry, swap-in-place, "words learned" counter). It fetches cases.json, so iterate by editing the JSON and refreshing.
• blueprint/serve.sh — bash serve.sh [port] then open template.html. Must be http, not file:// (fetch).

Always validate cases.json against schema.json before serving.

Rationalization table (from observed failures)

Excuse	Reality
"I'll just give the rewritten sentence as a starting point"	That's ghost-writing. Surface candidates; the user writes the line.
"I'll paraphrase the definition, it's faster"	Use WordNet via dict.py. Your paraphrase isn't a dictionary the writer can trust.
"A flat synonym list is enough"	No. Each candidate needs source label + official definition + (for ✓) verbatim usage, or the writer can't choose the right sense.
"lex search says the word isn't there → mark ◇"	lex search hits the distinctive-term index, not full text. Confirm with kwic.py before labelling.
"The corpus probably uses this word, I'll add a plausible sentence"	Fabrication. Only show sentences kwic.py actually returned. 0 hits → ◇.
"WordNet's first sense is fine"	Often the wrong POS/sense (coax→cable, seek→disk seek). Pass --pos; pick the apt sense.

Red flags — STOP

• You're about to output a finished version of the user's sentence.
• You're typing a definition from memory instead of running dict.py.
• You're writing a corpus usage sentence instead of pasting one from kwic.py.
• You labelled a word ✓ corpus without a kwic.py count > 0.

All mean: stop, run the tool, label honestly, hand the choice back to the writer.

Common mistakes

• Flagging precise prose that didn't need help (only de-slop what's actually vague).
• Over-reaching into sentence rewrites under the banner of "precision".
• Letting the corpus pool mismatch the register (AI-paper corpus is thin on literary/human vocabulary; say so rather than forcing weak hits).