Hai Naming

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

Overview

Treat naming as architecture expressed in language: a good name reflects the whole context, the
core actor's viewpoint, and the role the concept plays in the system. A name decides whether a
reader can understand the call flow, responsibility boundary, and operating subject without
translating between competing perspectives.

Do not turn naming into a mechanical debate about conventions. Conventions matter, but only
after the concept, responsibility, and system vocabulary are clear.

Three-Stage Naming

Every recommendation exposes three stages instead of only showing the final answer — this makes
the reasoning path visible, not just the verdict:

1. Research-stage naming: the rough name from quick context gathering — existing vocabulary,
   neighboring concepts, initial constraints. Shows what the current system seems to teach
   before deep reading.
2. Top-of-head naming: the intuitive, fast, "拍脑袋" name from first-principles sense of the
   concept. Allowed to be slightly bold, raw, or imperfect; its value is exposing the first
   mental model before existing wording biases it.
3. Final naming after reading: the recommended name after reading the relevant docs, code,
   call flow, product context, or system vocabulary. This is the name to ship unless a stated
   constraint blocks it.

If the three names differ, explain what changed your mind. If they converge, explain why the
name stayed stable after deeper reading.

Core Stance

These six principles are the judgment content; the Workflow and checks below reference them.

1. Name inside the whole context

Never name from an isolated snippet if broader context is available. First understand:

• The concrete scenario where a reader meets the name: reading a module, calling an API, editing
  a workflow, debugging a state transition, or using a product surface.
• The product/domain concept the name represents.
• The core operating subject: who or what acts, decides, owns state, or experiences the workflow.
• The layer and audience: product UI, domain model, API contract, persistence, runtime
  internals, tests, or tooling.
• Neighboring concepts and existing vocabulary.
• Lifecycle: how the thing is created, used, transformed, completed, archived, failed, retired.
• Boundaries: what this concept includes, excludes, owns, and delegates.

A name that sounds good locally can be wrong globally if it hides the main actor, duplicates an
existing concept, or names an implementation detail instead of the domain role.

2. Preserve information before shortening

Do not shorten names just to make them shorter. Brevity is only useful when the surrounding
context already carries the omitted information without forcing the reader to reconstruct it.

Prefer a longer explicit name when it prevents information compression, especially for:

• Exported functions, public APIs, domain entities, files, modules, events, workflow states, and
  cross-module types.
• Names that distinguish adjacent concepts: product vs domain, user work vs infrastructure
  execution, draft vs persisted state, request vs result, configuration vs runtime state.
• Code a reader is likely to enter from search results, stack traces, tests, docs, generated
  clients, or API contracts.

Short names are acceptable only when the scope is tiny and the missing words are immediately
visible in the same expression or block. If a reader has to infer a noun from the folder, a prior
paragraph, or tribal knowledge, the name is over-compressed.

3. Use the current core actor's viewpoint

Pick one viewpoint the naming set is organized around, then keep it stable across the module,
call chain, and related API surface. Do not name one function from module A's viewpoint and the
next from module B's viewpoint if they belong to the same conceptual flow — a hidden viewpoint
shift is worse than a slightly longer name.

Identify the viewpoint anchor before proposing or reviewing names:

• Product layer: name by what the user sees and intends.
• Domain layer: name by the durable business concept and its invariants.
• Runtime/infrastructure layer: name by execution responsibility, state transition, protocol role.
• Adapter/integration layer: name by the boundary being bridged.

If a name is hard to judge, ask: "From whose perspective is this name supposed to be obvious?"
If two adjacent names answer differently without crossing a real boundary, the naming is
inconsistent. When a real boundary is crossed, make the shift explicit through adapter, mapper,
handler, port, DTO, event, or boundary-specific vocabulary.

4. Follow the whole call flow

Check names against how the concept is called, passed, transformed, and returned — not only at
declaration sites. Trace: who creates or receives the value, which module owns the decision,
which module merely adapts/maps/forwards/stores/renders it, what the caller expects from the
name before opening the implementation, and where the perspective legitimately changes.

Names in one flow should read like one sentence from one stable viewpoint. If reading a call
chain forces the reader to switch between "what A sends", "what B receives", "what C stores", and
"what the UI displays" without explicit boundaries, the names are not aligned.

5. Name the concept, not the rule

fetch, get, load, create, build, manager, service, config, and context are not
automatically good or bad; their quality depends on what they mean in this codebase. Prefer a
name that captures the real concept over one that merely satisfies a generic convention. If the
project has a strong local vocabulary, follow it unless it actively misleads readers. Suffixes
like Manager, Service, Helper, Util, Data, Info, or Context are often a way to
avoid deciding what the thing actually owns.

6. Let naming expose design problems

When all candidate names feel awkward, do not keep generating synonyms — diagnose the design:

• Is one module mixing product, domain, and infrastructure concepts?
• Is one call flow switching viewpoints without an explicit boundary?
• Is the thing named by what it does today instead of what it owns?
• Are two different concepts sharing one name?
• Is one concept split across too many files?
• Is the current "thing" only a pass-through, glue layer, or temporary workflow step?

A fast trigger for this diagnosis: if a name needs a paragraph of explanation, or a hidden
backstory, to make sense, the concept or boundary is probably wrong — or the name is
over-compressed. Treat that friction as a design signal, not a wording problem.

Say so when the better answer is a design adjustment before a rename, and route per "Hand off
when" below.

Workflow

Mode 1 — Name a concept:

1. Produce the research-stage name from quick research context.
2. Produce the top-of-head name from first principles, before overfitting to existing wording.
3. Deep-read the call flow and concept, then produce the final name after reading (anchor one
   viewpoint per stance #3; decide what must stay visible per stance #2).
4. Propose 3-5 candidates per the rules in the template (include one vocabulary-aligned, one
   clean-concept, one explicit name for boundary-crossing concepts).
5. Recommend the final name and explain why the rejected ones are weaker; if none is satisfactory,
   recommend the design clarification needed first.

Mode 2 — Review or rename existing names:

1. Read the surrounding system, then build a small vocabulary map (actors, workflows, calling/
   called modules, layer-specific names for the same concept, overloaded terms).
2. For each important rename, show the three-stage path.
3. Flag names that harm understanding (wrong actor, mixed viewpoints, flattened concepts,
   over-compression, leaked implementation, stale legacy term, too generic, locally-consistent-
   but-globally-misleading).
4. Suggest changes in priority order — high-impact exported/API/domain names before small locals.

The expanded per-step detail lives in references/output-template.md.

Output

Mode 1 fills Context Read / Concept / Three-Stage Naming / What Changed After Reading /
Candidates / Recommendation. Mode 2 fills Vocabulary Map / Findings (each oldName -> suggestedName with location, three-stage path, problem, better model, viewpoint repair,
information restored, impact). Read references/output-template.md for the full fill-in blocks
before finalizing.

Practical checks

Mechanical checks the principles above do not already cover — use as checks, not laws:

• Symmetry: paired operations should read as peers (start/stop, open/close, encode/decode);
  asymmetric pair names imply the operations are not actually inverses, misleading the reader.
• Part of speech: entities read as nouns, actions as verbs, predicates as questions — so the
  reader can tell what a name returns without opening it.
• Consistency: the same concept uses the same word; different concepts do not share one word.
• Lifecycle states: state names should match real transitions, not arbitrary UI or
  implementation phases.

Hand off when

• The awkward name is really a module-boundary / abstraction problem (stance #6) — route to
  hai-architecture to fix the design before the rename.
• The concept is a data-model field question (should it exist, store vs compute, column vs jsonb)
  — route to entity-model-auditor.
• The user actually wants a bold direction change, not a name — route to geju.

What this skill is NOT

• Not a linter. Casing and style conventions are project-level constraints, not the center of the
  naming decision.
• Not a thesaurus. Do not solve unclear concepts by generating prettier synonyms.
• Not a rigid naming standard. Strong local vocabulary and architectural clarity beat generic
  formulas.
• Not only about identifiers. Product terms, API resources, domain entities, event names,
  workflow states, document titles, and file names all shape the system model.