hai-naming

Hai Naming

For Chinese readers, see SKILL.zh_CN.md. The English SKILL.md is the execution source of truth.

Purpose

Treat naming as a model of the system, not a thesaurus exercise. A useful name tells the intended reader what the concept is, who owns it, and how it differs from its neighbors without forcing them to reconstruct hidden context.

Choose the mode

• Quick naming: one local variable, function, prop, file, or concept. Give three to five candidates, recommend one, and explain the decisive distinction briefly.
• Naming audit: public or cross-module vocabulary, several related names, or a rename with migration impact. Build a vocabulary map, trace the call flow, and return prioritized renames.

Do not force an audit-sized reasoning trail onto a local identifier question.

Decision rules

1. Name in context. Read the declaration, callers, neighboring concepts, layer, audience, and lifecycle available in the user's scope. Never invent a global model from one isolated snippet.
2. Choose a viewpoint. Product names describe user intent, domain names describe durable concepts, runtime names describe execution responsibility, and adapter names describe the boundary crossed. Keep the viewpoint stable until a real boundary changes it.
3. Preserve decisive information. Shorten only when the surrounding expression carries the omitted meaning. Public and cross-module names should usually be more explicit than local ones.
4. Use one word per concept. The same concept keeps one term; different concepts do not share a convenient generic word.
5. Name ownership, not incidental mechanics. Manager, Service, Helper, Data, Info, Context, get, and build are acceptable only when they accurately express the local model.
6. Treat naming friction as evidence. If every candidate needs a paragraph of explanation, the concept may mix responsibilities or viewpoints. Recommend a design clarification instead of more synonyms.

Read references/principles.md when a public or cross-module decision needs the expanded context, call-flow, symmetry, lifecycle, or migration checks.

Workflow

Quick naming

1. State the concept, reader, layer, and nearest competing term.
2. Inspect the surrounding code or text the user supplied.
3. Generate three to five candidates that differ meaningfully, not cosmetically.
4. Recommend one and explain why the closest alternative loses.
5. Flag a design problem only when the evidence actually makes naming unstable.

Naming audit

1. Read the relevant declarations, callers, contracts, docs, and persisted/wire names.
2. Map actors, concepts, lifecycle states, layer-specific vocabulary, and overloaded terms.
3. Identify wrong viewpoint, lost information, stale vocabulary, collisions, and inconsistency.
4. Prioritize public/API/domain names before small locals.
5. For each rename, state old -> new, evidence, conceptual repair, affected surfaces, and whether compatibility is required by a real contract.
6. Separate the recommended vocabulary from the migration plan.

Output

Use the matching mode in references/output-template.md. A quick answer should remain conversational and compact. An audit must include evidence and migration scope, but it does not need to expose a performative “top-of-head” reasoning chain. Explain only what changed after reading when that change affects the recommendation.

Use a different skill when

• The name is awkward because module ownership or abstraction is wrong → hai-architecture.
• The question is whether a field should exist or where it belongs → entity-model-auditor.
• The user wants a bold direction change rather than a name → geju.
• The scope is an entire React component API, not one identifier → hai-architecture.

Not this skill

Do not act as a casing linter, rigid naming standard, or synonym generator. Project conventions constrain the answer, but conceptual clarity decides it.