jargon-extractor

Jargon extractor

Reads a set of documents, flags the internal terminology, acronyms, and jargon a new reader would not know, and maintains a single alphabetized JARGON.md glossary across runs.

The work splits into three phases with different failure modes and different homes. Extraction is judgment-heavy: deciding whether a word counts as jargon depends on reading the document. Correlating and merging is also judgment-heavy: deciding whether two definitions describe the same concept. Filing is mechanical: sorting, deduplicating, and writing the file correctly every time. Extraction and merging happen in disposable subagent contexts that report back only a short summary; filing is a deterministic script that reads and writes files directly on disk without needing their contents echoed into any model's context at all. The orchestrator's own context only ever holds file paths and small counts, never the bulk of the extracted terms.

Both extraction and merging run as subagents, but only once each per run, not once per wave.

Execution flow

wave 1 (up to 5 files)        wave 2 (up to 5 files)      ...
+---------+  +-----------+    +---------+  +-----------+
| file A  |->| extractor |    | file F  |->| extractor |
+---------+  +-----------+    +---------+  +-----------+
     ...          ...              ...          ...

each extractor writes its findings to a file and returns only a
one-line confirmation; waves run one after another, capped at 5
concurrent extractors at a time, purely to bound concurrency

once every wave has finished:

  all extraction file paths            +---------+     +--------------------+
  + the glossary path        ------->  | reducer | ---> | merge_jargon.py    |
                                        | (whole  |      | upserts into        |
                                        |  run)   |      | chosen JARGON.md    |
                                        +---------+      +--------------------+

  the reducer reads every extraction file and the current glossary
  itself, correlates and merges once across the whole run, and
  writes one entries file plus a short summary