naming-helper

name	naming-helper
description	Proposes and audits names for code identifiers, APIs, files, and config keys — generating consistent, intention-revealing candidates that follow the project's existing conventions (case style, domain vocabulary) and avoiding misleading or abbreviation-heavy names.
when_to_use	User asks 'what should I call this', to rename for clarity, to name a function/variable/endpoint/flag/table, or to audit a diff for naming consistency before review.

When to Use

• "What should I call this?" / "Better name for X?" / "Rename this for clarity."
• Naming a new function, variable, class, endpoint, CLI flag, env var, DB table/column, or config key.
• Auditing a diff or file for naming consistency before code review.

Skip when: the name is dictated by an external contract (HTTP spec header, third-party API field, framework magic name like getServerSideProps) — match the contract exactly, don't "improve" it.

Steps

1. Infer conventions before proposing. Grep the surrounding scope, do NOT guess:
   • Case style per kind — run e.g. rg '\b(fn|def|func|function|const|let|var)\s+\w+' <dir> and tally: are functions camelCase, snake_case, PascalCase? Booleans is*/has*/should*? Constants SCREAMING_SNAKE? Endpoints kebab or snake? Env vars UPPER_SNAKE?
   • Domain vocabulary — does the codebase say user or account, cancel or void, delete or remove? Reuse the term already in use; don't introduce a synonym.
   • Verb register for siblings — list the neighbors (rg 'def (get|fetch|load|read|find)_' <module>) and match the dominant verb instead of mixing.
2. Propose 2-3 candidates per item, each with a one-line rationale, then mark the recommended one. Format:

   processData()  →
     1. normalizeOrderRows()   ← recommend: says WHAT (normalize) + ON WHAT (order rows)
     2. cleanOrders()          ← "clean" is vague, what does clean mean here?
     3. transformOrderData()   ← "Data" is a noise word; "transform" hides intent
   

3. Apply the quality bar to filter candidates:
   • Intention-revealing: name answers why it exists / what it returns, not how it's implemented.
   • Searchable: no single-letter (except loop indices i/j in ≤3-line scopes) and no ambiguous 2-char names.
   • Pronounceable, no encoded type (strName, arrItems, bIsValid — drop the prefix).
   • No noise words: Data, Info, Manager, Helper, Object, Stuff, tmp, do*, handle* unless they add real meaning.
   • No misleading terms: userList that's a Set/Map; getX() that mutates or does I/O; isReady that returns a count.
   • Length scales with scope: tight loop var short; module-level export descriptive.
4. Consistency check across siblings. Flag mixed vocabularies for the same concept:
   • Verb drift: getUser + fetchOrders + loadCart in one module → pick one verb.
   • Antonym pairs must match: open/close, begin/end, add/remove, start/stop — not add/delete.
   • Singular/plural per cardinality: user returns one, users returns a collection.
   • Same prefix family: if one flag is --dry-run, a sibling should be --no-cache, not --skipCache.
5. Audit mode (when given a diff/file): scan only changed/added identifiers → output a table current → suggested | reason. Names only — never change behavior, signatures' arg order, or types. If a rename touches a public/exported symbol, list every call-site that must change and say so explicitly; do not silently break callers.

Common Errors

• Inventing a convention instead of detecting one. If you didn't grep, you don't know the case style — a camelCase suggestion in a snake_case file is an instant reject. Detect first.
• Renaming public API / serialized keys as if they're free. A DB column, JSON field, env var, or exported function rename is a breaking change + (for columns) a migration. Flag it as breaking, don't bundle it into a "cleanup."
• Reserved words & collisions. Check the target name isn't a language keyword (class, type, enum, default), a builtin (id, list, dict, len, type), or already taken in the same scope. A name that shadows a builtin is worse than the original.
• Over-shortening. cfg, usr, ctx, req/res are fine ONLY if already idiomatic in this codebase; otherwise expand. Never abbreviate to save typing — searchability beats brevity.
• Boolean inversions. Renaming disabled → enabled (or vice-versa) flips meaning at every call site. If you flip polarity, that's a behavior change — flag it, don't do it silently.
• Hungarian / type-encoded names survive in legacy spots; match the file's existing pattern even if you dislike it — consistency within a file beats global purity.

Verify

• Recommended name is in the file's detected case style (re-grep one neighbor to confirm).
• Name reuses existing domain vocabulary, no new synonym introduced.
• No collision: the name isn't already declared in scope and isn't a keyword/builtin.
• Verb/antonym/cardinality matches its siblings.
• For audit/rename output: every breaking rename (public symbol, serialized key, env var, column) is explicitly tagged as breaking with its call-sites/migration noted; no behavior, type, or signature was altered — names only.