Name It Better

Name it better

Purpose

Produce better name candidates for anything that needs one: an identifier, file, module, skill, repo, or domain term. Then hand the human a scored shortlist to choose from. The dominant trigger is a reactive retry: a name was just suggested and rejected, and the same context that produced it will only produce more of the same. So the generators run BLIND to the conversation, from distinct lenses, to break the anchor. A blank-slate naming request is the same machinery without a rejected incumbent.

The human always picks. This skill narrows and recommends; it never auto-locks a name.

Criteria. Cite the source of truth, do not copy it

Score against the consuming organization's naming criteria, resolved from its own context, never from a baked-in path:

1. Declared conventions win. When the consuming project names where its naming and domain-language conventions live, its CLAUDE.md, .claude/rules/, or a shared standards source it points to, score against THAT. Read the criteria there; do not restate them here. A criterion the user wants that is missing from those conventions flows UP into them (their standards change), not hardcoded into this skill.

2. None declared → the general criteria grounded in context/sources.md, applied in this research-ordered priority. A higher tier breaks ties over every tier below it:

   1. Semantic accuracy (anti-misleading). The name must not lie about what the thing does. A misleading name is empirically worse than a vague or meaningless one, so this outranks everything below.
   2. Scope fit. Length and detail scale with the thing's scope and lifetime; never repeat information the surrounding context (package, type, module) already supplies.
   3. Comprehensibility. Prefer full, intention-revealing words over abbreviations, bounded: established idioms and conventionally short names (loop i, a receiver) are not penalised.
   4. Trigger / evocative utility. How well the name cues recall at the moment of use. That is a genuine tiebreaker, but the lowest-priority one.

   This ordering governs the scoring and judging steps. It is the fallback only: a consuming project's declared criteria (rule 1) override it wherever the two differ.

Semantic vs syntactic. The modality layer

Naming criteria split in two. The semantic layer covers accuracy, scope fit, no collisions, and noun-for-a-thing / verb-for-an-action. It carries across every modality, and is what the generators and judges optimise. The syntactic layer covers casing, length budgets, and separator and affix conventions. It is modality- and vendor-specific; apply it as a final shaping pass over the semantic winners, never as a scoring axis that overrides meaning. Shaping can change the string, so RE-RUN the full merge-step filter set on the shaped forms: dedupe, collision, reject-list, word-blocklist. Two distinct candidates can normalize to one string (SessionStore and session-store → session_store), a normalization can recreate an existing sibling or a rejected incumbent, and a required affix can introduce a blocked word (Order → OrderManager) that the pre-scoring filters could not match.

• Route documented conflicts out; do not pick a side. Where authorities genuinely disagree on abbreviation policy, acronym casing, or camelCase vs snake_case, this skill takes no house position. Defer to the consuming ecosystem's own style guide (rule 1's declared conventions); the conflicting primaries are catalogued in context/sources.md.
• Claude Code skills are the sharp special case. For a skill, the DESCRIPTION, not the name, is what drives model-side discovery. So optimise the name for human semantic accuracy, and put the trigger phrases and example requests in the description, not the name. A skill loadable as primed context at conversation start must also be temporally neutral: the name has to read valid before any work exists, so a candidate that presupposes completed output ("critique your run") fails for a skill that can fire cold.

Default pass

1. Build the structured context brief. This brief, NOT the conversation, is all the generators receive, so it must carry every field they need, each captured by name:

   • Target modality. What KIND of thing is being named (function, type, module, file, CLI command, skill, domain term): it fixes noun-for-a-thing vs verb-for-an-action and tells the final shaping pass which syntactic conventions apply.
   • Responsibility. What the thing DOES, in one line.
   • Firing / usage context. When it is reached for, and how it reads at the call site.
   • Scope boundaries. What it is NOT: the adjacent things it must not be confused with or blur into.
   • Collision vocabulary. The existing sibling names it must not duplicate.
   • Terms of art. The established names the field or domain already uses for this act or thing, with their ACTUAL researched meanings, not recalled ones. Research them before the fan-out: a term whose field meaning diverges from this target is misleading (criterion 1) and the divergence belongs in the brief so generators neither borrow it blindly nor miss the honest established term.
   • Word-level blocklist. Individual words ruled out, each WITH its reason (overloaded, misleading, collides, already rejected) AND its provenance: user-stated or agent-inferred. An agent-inferred entry is a proposal to confirm with the user, never a silently hard constraint. An assumed blocklist word can eliminate the honest winner.

   Rejected incumbent NAMES deliberately stay out of the brief. The main thread holds them as its reject list and disqualifies matches at merge time (anti-anchoring: a generator shown a rejected name re-derives it). Only the abstracted REASON a name failed enters the brief, as a blocklist entry or scope-boundary correction.

   The brief mirrors the replicated concept → word → structure naming model (grounded in context/sources.md): the named fields fix the concepts and constraints; the generators then choose the words per concept and arrange the structure.

2. Fan out blind generators. Spawn ~3 fresh-context subagents, each seeded ONLY with the brief (blind to this conversation and to each other), each working a distinct lens:

   • responsibility-literal. Name exactly what it does;
   • moment-of-use. Name for how it reads at the call site;
   • domain-lore. Name from the domain's ubiquitous language.

   Running them blind and independent is deliberate anti-anchoring; the method grounding is in context/sources.md.

3. Merge and score. For a name used as an utterance, a skill, command, or anything invoked by saying it, apply the sentence-form test as an early filter before scoring: is the candidate the imperative you would actually say, readable cold with no context? Contentless idioms (a bare "check", "take stock") fail it even when they score well on the criteria below. For a skill loadable as primed context, apply the temporal-neutrality test in the same early filter: a candidate that presupposes completed work fails before scoring, however accurate it is once work exists. Then pool the candidates, dedupe, and disqualify any candidate that matches the rejected incumbent (if any), that contains a USER-STATED word-level blocklist entry (a generator can miss the brief's constraint; the merge step enforces it), or that collides with the existing vocabulary. The rejected-incumbent list is carried by the main thread as an explicit reject list, never shared with the generators. A candidate containing only an AGENT-INFERRED blocklist word is not disqualified. It stays in, flagged with the inferred concern, so the user's pick confirms or overrides the inference (provenance rule above). Score every surviving candidate against the criteria resolved above, breaking ties by their declared priority order.

4. Shortlist + recommend. Present a short ranked list with a one-line rationale per candidate and a single RECOMMENDED pick, marked and listed first.

5. Human picks. Stop and let the user choose. Do not apply the name.

Iterate on the rejection reason

If the human rejects the shortlist or a specific candidate, the rejection is data, not a dead end. Capture the REASON as an explicit new constraint and fold it into the next round's brief before regenerating:

• a word that drew the objection becomes a word-level blocklist entry, carrying that reason;
• a "wrong scope / wrong thing" objection becomes a scope-boundary correction;
• a "these all miss what matters" objection reweights the criteria for the next round, but only within the space the consuming project's declared conventions leave open. Declared conventions still win: a rejection that contradicts them routes upstream as a proposed convention change, never a silent local reweighting.

Rejected names and rejected words never re-enter. The reject list and the word-level blocklist only grow across rounds. Each new round is a fresh blind fan-out seeded with the corrected brief, never a patch of the last round's candidates.

tournament action

When $ARGUMENTS contains tournament, run this in place of the default pass.

/naming:name-it-better tournament is for a high-stakes name that will be hard to refactor later. Widen to ~5 generators (optionally different models), then run elimination rounds with independent scoring judges until one candidate remains, and present it plus the runners-up for the human choice.

The default pass's merge filters still apply BEFORE the elimination rounds begin, including the sentence-form and temporal-neutrality tests for utterance and cold-loadable names and the blocklist provenance rule: pool the widened candidates, fail contentless idioms and completed-work-presupposing names early, and disqualify any that match the rejected incumbent, contain a user-stated blocklisted word, or collide with the existing vocabulary (agent-inferred blocklist matches enter the bracket flagged, not disqualified).

Settle the scoring criteria before the generators return, and write them down. The criteria are still resolved from the consuming project's own declared standards, not chosen here. Which of them decide this name, and how they rank, is a judgement, and it must be made while the pool is still unknown. A rubric fixed after the candidates land gets shaped by them, and one that already fits the pool cannot eliminate anything: the independent judges then score against a standard the pool itself authored. A criterion found missing mid-bracket still routes upstream, and adding it means re-scoring the round it changes.

HONEST FRAMING: a "naming tournament / bracket" is NOT a documented software-naming technique. This mode ADAPTS elimination brackets plus pairwise social-choice scoring as a convergence mechanism. See context/sources.md. Present it as such, not as an established standard.

Adjacent skills. Hand off, do not overlap

• The target is a domain concept. Naming a domain term well depends on first settling what the concept IS, not just its label. Route that to a domain-modelling capability, then name the settled concept once it returns. Pointer only. This skill does not do the domain modelling.
• A rename is already decided. Sweeping references after the fact → a rename-references capability. This skill picks the name; that one propagates it.

Invoke an adjacent capability through its slash command when present; degrade to prose guidance when it is absent.

What this skill does NOT do

• Never auto-locks a name. It always ends at a human choice.
• Does not apply the rename. Propagating a chosen name across call sites is a rename-references capability's job.
• Does not copy or invent criteria. It scores against the resolved source of truth; missing criteria route upstream, not into the skill.
• Does not claim tournament mode is a documented technique. It is an adaptation, flagged as one.
• Does not pick a house side on documented style conflicts. Abbreviation policy, acronym casing, and casing style route to the consuming ecosystem's own style guide, never a baked-in verdict.

Gotchas

• If the generators are fed the conversation instead of just the brief, the anti-anchoring purpose is defeated. They will re-derive the rejected name. Seed them with the brief ONLY.
• A blind generator can still independently re-derive the rejected incumbent (common for generic labels like Manager or Context). That is not a blinding failure. The main thread's reject list disqualifies it at merge time regardless of how a candidate was produced.
• A candidate that scores well but collides with existing vocabulary is disqualified, not shortlisted. Collision-check before scoring.
• A rejected candidate's REASON must become a brief constraint (a blocklist word, a scope correction, a criteria reweight) before the next round, or the blind fan-out re-derives the same reject.
• tournament costs several generators plus judges; reserve it for names that are genuinely expensive to change, not routine locals.