Jargon Leak

Jargon Leak

Overview

Every project grows an internal vocabulary — codenames, mode names, abbreviations, team shorthand. The audit principle: that vocabulary must not appear on surfaces external consumers see or type, and you DISCOVER each project's vocabulary fresh; you never arrive with a fixed word list.

When to use / when NOT

Use when:

• Auditing before a first public release, open-sourcing, or npm/registry publish
• Extracting app code into a reusable library that must stay product-agnostic
• Preparing a handoff (see handoff-readiness) or running a full release pass (see release-audit)
• A reviewer asks "would an external user understand this name?"

Do NOT use for:

• Internal-only repos with no public or reusable surface (nothing can leak)
• General naming quality unrelated to public exposure — see code-audit
• Prose tone/AI-voice problems — see humanizer
• Building a domain glossary as the end goal — see ubiquitous-language (use it AFTER this audit to canonize the chosen terms)

How it works

1. Detect the project's shape. Read the repo root: package manifests, workspace layout, docs config, publish/release scripts. Determine the distribution channels: published npm packages? copy/registry distribution (source shipped into consumer repos)? CLI binary? docs site? hosted app? Each channel defines what counts as "public."

2. Build the internal vocabulary list (candidates, then classify):

   • Read internal docs: CONTRIBUTING, AGENTS.md/CLAUDE.md, ADRs, internal READMEs, architecture notes.
   • Mine git log --oneline -200 for recurring terms.
   • Compare directory/workspace names against public package names — mismatches often expose codenames.
   • rg -c candidate terms separately in private code vs user-facing copy: a term dense in internals but absent from public copy is internal vocabulary.
   • Classify each term: internal-only (codename, mode name, team shorthand), product term (the product's real public name/concepts), or generic (industry-standard: CLI, SSR, ARIA — never a leak).

3. Enumerate the public/reusable surfaces. Anything an external consumer sees or types:

   • Published package names and every exported API symbol (walk exports maps / index entries)
   • Exported design tokens, CSS variable names, theme keys, data attributes, class prefixes
   • User-visible UI strings, labels, placeholders, error messages, CLI --help text and flag names
   • Documentation prose, README, code examples consumers will copy
   • Registry item names, config file keys, env var names, file names shipped via copy distribution

4. Scan for leaks. For each internal-only term, rg -i across the surfaces from step 3. Check case/format variants: kebab-case token, PascalCase symbol, SCREAMING_SNAKE env var, prose mention. Also sweep for dev-only labels: WIP, TODO in shipped strings, placeholder copy, internal ticket IDs.

5. Judge each hit — surface type decides legitimacy, identifier role decides cost:

   • Product term on a product surface (the product's own app UI, its docs site) → legitimate, not a finding.
   • Internal term — or even the product term — on a product-AGNOSTIC reusable surface (generic UI library, copied source, exported tokens) → leak.
   • Illustrative example only: a generic UI library exporting --tui-accent-color because the parent product has a TUI mode — load-bearing leak; external theme authors must type a name referencing a product mode they've never heard of.
   • Adjacent finding: naming↔content mismatch — a symbol named X that actually exports Y behavior. Flag it; it confuses consumers the same way.

6. Price the migration. Public-API/token/flag renames ripple through docs, examples, generated artifacts, registries, and consumer code. State the ripple per finding and recommend doing high-cost renames BEFORE the first public release — after release they are breaking changes. For repo-wide passes or iterative fix-verify cycles, drive this skill via convergence-loop.

Quality bar

Cost rubric:

• High — consumers type or programmatically depend on the term: API symbol, token, CLI flag, config key, registry item ID. Renames are breaking.
• Medium — user-visible copy, error messages, doc headings, example code. Renames are cheap but visible.
• Low — buried doc mention, comment in copied source, changelog entry.

Output

## Jargon Leak Report

Internal vocabulary detected:
- <term> — <one-line meaning, where it lives internally>
- ...

### Leaks (grouped by surface)

#### <surface — e.g. "Exported tokens (packages/theme)">
| Term | Location | Cost | Suggested neutral name | Migration ripple |
|---|---|---|---|---|
| <term> | <file:line or symbol> | High/Med/Low | <name> | <docs, examples, generated artifacts, consumers affected> |

### Adjacent: naming/content mismatches
| Symbol | Name claims | Actually does | Suggested fix |
|---|---|---|---|

### Verdict
- Leaks: high N / medium N / low N
- Release-blocking (rename before first public release): <list or "none">
- Recommendation per remaining term: rename now / accept as product term / add glossary entry (see ubiquitous-language)

Common mistakes

• Arriving with a fixed jargon word list instead of discovering THIS project's vocabulary first.
• Flagging legitimate product names on product surfaces — the product's own app may say its own name.
• Treating industry-standard abbreviations (SSR, ARIA, CLI, JWT) as jargon.
• Missing case/format variants — the codename hides as a kebab-case token even when the PascalCase grep is clean.
• Suggesting a rename without listing the ripple (docs, examples, generated artifacts, registry JSON, consumers).
• Ignoring dev-only labels in shipped strings (placeholder copy, WIP markers, internal ticket IDs) because they aren't "names".
• Drifting into prose tone editing (that is humanizer) or general naming critique (that is code-audit).