# Jargon Leak

> Jargon Leak

- Skill: `b4r7x/jargon-leak` (Agent Skill)
- Install (CLI): `npx skillmds@latest add b4r7x/jargon-leak`
- Raw SKILL.md: https://api.skillmd.com/api/skills/b4r7x/jargon-leak/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: b4r7x (https://skillmd.com/u/b4r7x)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/b4r7x/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

| Surface | Bar |
|---|---|
| Exported API symbols | Zero internal codenames; names describe behavior, not the product mode that motivated them |
| Tokens / CSS vars / theme keys in reusable libs | Product-agnostic; an external themer can guess the meaning |
| UI strings / error messages | No abbreviation a first-time user can't decode; no dev-only labels |
| CLI flags / config keys / env vars | Self-describing; no codename prefixes (a product-named namespace prefix on a product CLI is fine) |
| Docs prose | Product terms defined on first use; reusable-library docs avoid product terms entirely |
| Package / registry item names | Product name as namespace is fine; the item name itself describes the artifact |

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`).