I am *shocked* by how many AI engineers don't do a comprehensive naming review. This is an easy 80% reduction in AI errors. Actually.
I'll share it with you...first these are literally latent space machines, there is NOTHING more important than names.
I can't even begin to tell you what a difference this makes in my projects, it's absolutely night and day. If I use this on each new round of development the amount of confusion, crossing wires, messiness, general AI mistakes are probably reduced by 80% over the course of a project.
@
@NameReview
```
You are performing a boundary-aware naming analysis on a software artifact.
First determine the target of analysis.
The target is usually one or more of:
1. a plan
2. a set of beads or work items
3. an existing codebase
If the user has not clearly specified the target, ask which of these you are analyzing before continuing.
Purpose
Your job is not to do surface-level renaming.
Your job is to understand the system’s conceptual boundaries and improve naming so that:
- each concept has a clear primary name,
- each name points to one concept,
- neighboring concepts are easy to distinguish,
- humans and coding AIs are less likely to confuse modules, responsibilities, states, or ownership.
Core operating principles
- Be boundary-first, not word-first.
- Familiarize yourself with the existing systems before suggesting any renames.
- Be conservative and idempotent: preserve names that are already good.
- Prefer convergence over churn.
- Optimize for long-term clarity, not novelty.
- Do not rename simply for style. Rename where clarity materially improves.
Step 1: Familiarize yourself with the system
Before evaluating names, build a rough model of the system:
- major domain concepts
- modules, packages, folders, and subsystems
- layer boundaries
- ownership boundaries
- dependency and call relationships
- public interfaces and external integrations
- data model, API, event, job, and workflow boundaries
Infer this from whatever artifacts are available, such as:
- plans
- beads or work items
- architecture notes
- README files
- folder structure
- imports and dependencies
- interfaces and schemas
- tests
- call patterns
- comments and documentation
Distinguish domain concepts from implementation details.
Step 2: Build a concept and vocabulary map
Create a map of:
- concept
- current names used for that concept
- where those names appear
- owning boundary or module
- adjacent or easily confused concepts
- whether the naming is canonical, inconsistent, overloaded, or ambiguous
Also identify:
- synonyms being used for the same concept
- the same word being used for different concepts
- names that have drifted away from the actual responsibility
Step 3: Evaluate names using this rubric
A strong name should be:
- specific, not generic
- bounded to the actual responsibility
- clearly distinguishable from nearby concepts
- consistent with the project’s vocabulary
- stable across likely implementation changes
- readable in code, docs, logs, and discussion
- searchable and easy to grep
- role-revealing when relevant, such as model, service, adapter, policy, event, command, store, schema, record, request, response, or job
Step 4: Look specifically for naming failure modes
Check for:
- one word used for multiple concepts
- multiple words used for the same concept
- folder or module names that do not match the responsibility inside
- names that blur boundaries between modules or layers
- vague generic names such as Manager, Helper, Utils, Processor, Handler, Engine, Core, Common, Misc, Data, or Info unless narrowly justified
- weak suffix or prefix distinctions such as XData, XInfo, XPayload, NewX, X2
- unclear state distinctions such as:
- draft vs submitted
- requested vs actual
- template vs instance
- definition vs execution
- source vs target
- input vs output
- internal vs external
- singular/plural inconsistency
- verb/noun inconsistency
- entity/model/schema/DTO/record confusion
- names whose scope is broader or narrower than the thing they name
- names that are clever but not explicit
- names that force an AI or reader to infer too much from context
Step 5: Propose improvements conservatively
When proposing changes:
- prefer the smallest set of renames that gives the largest clarity gain
- preserve established domain language unless it is actively misleading
- prioritize high-leverage names first:
1. core domain vocabulary
2. subsystem/module/package names
3. public APIs and shared types
4. important classes, services, and functions
5. lower-level internals and locals
- do not rename a local symbol if the real problem is the parent concept or boundary
- explain the naming rule behind the recommendation so future names stay aligned
- prefer names that remain clear when seen out of context
Step 6: Optimize for both humans and coding AIs
Favor names that:
- encode real distinctions explicitly
- avoid overloaded roots
- make ownership or boundary visible when that matters
- make state visible when that matters
- make external vs internal meaning visible when that matters
- reduce the chance that two nearby concepts will be conflated during implementation
In general:
- one concept should ideally have one primary name
- one primary name should ideally refer to one concept
- related names should form coherent families
- contrasting concepts should contrast clearly in their names
Step 7: Produce output in this structure
1. Target analyzed
2. Boundary and system map
3. Canonical vocabulary proposal
4. Naming issues found
5. Recommended renames, prioritized
6. Risks to prevent going forward
7. Open questions or assumptions
For each naming issue, include:
- current name
- location or scope
- intended concept
- why it is confusing
- whether the problem is semantic, boundary-related, state-related, or stylistic
- recommended action: keep, rename now, rename later, or monitor
For each rename recommendation, include:
- proposed new name
- rationale
- confidence
- blast radius
- whether it should be changed immediately or only when that area is next touched
Special handling by target
If the target is a plan or a set of beads/work items:
- propose names that are implementation-ready
- align plan/work-item names to likely module and domain boundaries
- flag names that will create confusion once they become code, APIs, or schemas
If the target is an existing codebase:
- distinguish between public/API names, shared internal names, and purely local names
- weigh blast radius and compatibility before recommending renames
If the target combines plan plus codebase:
- align future planned names with the existing canonical vocabulary unless the existing vocabulary is itself the source of confusion
Important final rule
Do not begin by renaming.
Begin by understanding the system, its boundaries, and its vocabulary.
Only then propose naming changes.
```