Use when reviewing or designing names for plans, beads, work items, architecture docs, codebases, APIs, schemas, modules, states, or domain vocabulary where terminology drift, overloaded concepts, boundary ambiguity, or AI-confusing naming may exist.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Use when reviewing or designing names for plans, beads, work items, architecture docs, codebases, APIs, schemas, modules, states, or domain vocabulary where terminology drift, overloaded concepts, boundary ambiguity, or AI-confusing naming may exist.
metadata
{"category":"developer tools","blurb":"Boundary-first naming review that maps concepts before recommending small, evidence-backed renames for code, plans, schemas, and docs.","keywords":["name","review"]}
Name Review
Boundary-aware naming review improves the system's conceptual vocabulary. Do not begin by renaming. First understand the target, its boundaries, and the concepts that names are supposed to carry.
Core Principle
A rename is only an improvement when it makes the system easier to reason about across time, contributors, tools, and boundaries.
Optimize for:
one concept with one primary name
one primary name that points to one concept
related concepts forming coherent name families
contrasting concepts contrasting clearly
names that remain clear out of context
When To Use
Use this skill when the user asks to review, improve, audit, defuzz, or design names in:
a plan, PRD, spec, architecture note, or implementation proposal
beads, issues, tickets, tasks, or work items
an existing codebase, package, module, API, schema, CLI, event set, or data model
a mixed target where plans and code need vocabulary alignment
any artifact where terms feel overloaded, vague, misleading, inconsistent, or likely to confuse coding agents
Do not use this skill for pure prose copyediting, brand naming, or stylistic polish unless those names also affect system boundaries or implementation concepts.
Required First Move: Determine The Target
Identify the target before reviewing names. The target is usually one or more of:
plan
beads or work items
architecture docs
existing codebase
mixed plan plus codebase
If the user has not clearly specified the target and no artifact can be inferred from context, ask which of these you are analyzing before continuing. If there is an obvious artifact in context, state the target assumption and proceed with a bounded review.
Record:
artifact type and scope
evidence inspected
evidence missing
whether recommendations are review-only or implementation-ready
whether public contracts or persisted names are in scope
Default to review-only. Do not edit files, rename symbols, rewrite plans, or modify work items unless the user explicitly asks for implementation.
Operating Rules
Be boundary-first, not word-first.
Familiarize yourself with the system before judging names.
Preserve names that are already good.
Prefer convergence over churn.
Do not recommend style-only renames.
Do not invent a cleaner vocabulary that is incompatible with the system's actual meaning.
Do not flatten real distinctions just because two names look similar.
Treat public APIs, persisted schemas, event names, CLI commands, URLs, package names, and user-facing names as migration-sensitive.
Ignore incidental local names unless they create real ambiguity or expose a larger conceptual problem.
Prefer the smallest set of high-leverage renames.
Accept "no findings" as a valid outcome when the vocabulary is already clear or the available evidence does not justify churn.
Boundary And System Map
Before evaluating names, build a rough model of the target. Scale depth to evidence and requested scope; do not exhaustively inspect every surface unless the user requested a broad audit, but do not skip this step.
Map:
major domain concepts
actors, users, systems, and external integrations
modules, packages, folders, subsystems, or work streams
ownership boundaries: which module, team, work item, or artifact owns each concept
lifecycle and state boundaries
dependency and call relationships
public interfaces and external contracts
data model, API, event, job, command, workflow, and storage boundaries
source and target boundaries for data flow
Distinguish domain concepts from implementation details. Domain names should not be replaced with generic software names unless the domain name is misleading.
Concept And Vocabulary Map
Create a vocabulary map before proposing changes.
For each concept, track:
concept
current names used
locations or surfaces
owning boundary or module
adjacent or easily confused concepts
status: canonical, inconsistent, overloaded, ambiguous, misleading, or acceptable
whether the name is public, shared internal, or local
Look across all available naming surfaces:
directories, files, packages, modules
classes, types, interfaces, schemas, DTOs, records
functions, methods, commands, jobs, events
routes, endpoints, database tables and fields, configs
tests, fixtures, comments, logs, metrics, docs
plan headings, milestones, beads, issue titles, acceptance criteria
Same-name/different-concept conflicts are usually higher priority than simple synonym drift because they cause readers and coding agents to merge concepts incorrectly.
Review Lenses
Run the naming review through these lenses and cross-link findings back to the concept map.
Lens
Focus
Boundary
Does the name expose, hide, or blur the correct boundary?
Concept
Does the name point to one real concept?
Responsibility
Does the name match what the module or artifact owns?
State
Does the name preserve lifecycle distinctions?
Layer
Does the name mix domain, UI, persistence, infrastructure, or protocol language?
Publicness
Is the rename cost different because the name is external, persisted, or user-facing?
Searchability
Can humans and agents grep, discuss, and trace the concept reliably?
Family
Do related names form a coherent family without weak suffixes?
Naming Rubric
A strong name is:
specific, not generic
bounded to the actual responsibility
distinguishable from nearby concepts
consistent with the project's vocabulary
stable across likely implementation changes
readable in code, docs, logs, diagrams, tickets, and discussion
searchable and easy to grep
role-revealing when the role matters
Useful role words include:
model
service
adapter
policy
event
command
query
store
repository
schema
record
request
response
job
projection
snapshot
definition
execution
Use role words only when they add real boundary information. Do not add suffixes as decoration.
Failure Modes To Check
Look specifically 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 ownership, modules, or layers
names that leak implementation detail into domain language
domain names replaced by generic software terms
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, BaseX, or CommonX
unclear state distinctions: draft versus submitted, requested versus actual, template versus instance, definition versus execution, planned versus observed, source versus target, input versus output, internal versus 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
clever names that are not explicit
abbreviations that hide important concepts
overloaded roots that force readers to rely on surrounding context
work item titles that sound elegant but no longer identify a concrete deliverable
architecture component names that say category but not responsibility
code names that are semantically right but too expensive to change now
Target-Specific Guidance
Plans, PRDs, And Specs
Optimize for implementation-ready concept formation.
Check:
whether feature names hide multiple concepts
whether future modules, APIs, schemas, jobs, or events have stable names
whether product, domain, and implementation terms are mixed
whether vague terms such as "system", "workflow", "pipeline", "engine", "sync", or "manager" stand in for unresolved design
whether planned state names distinguish definition, request, execution, observation, and result
Treat plan vocabulary as provisional unless supported by implementation or domain evidence. Prefer vocabulary proposals over hard rename mandates when the design is not yet settled.
Beads, Issues, Tickets, And Work Items
Optimize for executable work boundaries.
Check:
whether each title names a concrete deliverable
whether dependencies and sequencing are visible
whether the name identifies the right layer: product, domain, infra, migration, test, docs, operations
whether nearby work items use competing names for the same concept
whether similar titles actually describe different lifecycle phases
whether acceptance criteria use the same vocabulary as the title
Do not abstract work item names past the point where a contributor can tell what to build.
Architecture Docs
Optimize for responsibility and boundary clarity.
Check:
whether a named component is a domain concept, module, adapter, storage mechanism, protocol, external system, or UI concept
whether the name describes what the component owns rather than how it happens to be implemented
whether external systems are clearly distinguished from internal abstractions
whether diagram labels, prose, APIs, and schemas use compatible vocabulary
whether broad names like Orchestrator, Coordinator, Engine, or Service hide multiple responsibilities
Architecture names should make the next boundary obvious.
Existing Codebases
Optimize for observed usage and safe convergence.
Start with repo instructions, folder structure, entrypoints, tests, schemas, public interfaces, and recent or relevant code paths. Inspect call sites and adjacent names before judging an identifier.
Classify each name as:
public or external contract
persisted or serialized contract
shared internal concept
module-private concept
local incidental symbol
For public, persisted, generated, or serialized names, weigh compatibility and migration cost before recommending a rename. When the rename is correct but expensive, mark it "rename later" or "rename when next touched" unless the current name is actively dangerous. Include a concrete migration note: coordinated replacement, version boundary, schema migration, generated artifact update, release note, or "do not rename now."
Mixed Plan Plus Codebase
Compare intended vocabulary with implemented vocabulary without assuming either is canonical.
Classify drift:
plan term absent from code
code term absent from plan
same term, different meaning
different terms, same meaning
plan abstraction too broad
code abstraction too broad
plan stale after implementation learning
implementation leaked infrastructure terms into domain language
Align future planned names with the existing canonical vocabulary unless the existing vocabulary is itself the source of confusion.
Recommendation Priority
Prioritize recommendations in this order:
core domain vocabulary
subsystem, module, package, or architecture boundary names
public APIs, schemas, routes, events, commands, and persisted fields
shared internal types, classes, services, functions, and jobs
lower-level internals and local names
Use this severity scale:
Priority
Meaning
Typical action
P1
Same name for different concepts, misleading boundary, or high-risk public confusion
Rename now or create a concrete migration plan
P2
Same concept has multiple shared names, or responsibility has drifted
Rename now if scoped, otherwise rename when next touched
P3
Scope, state, role, or family naming is weak but contained
Monitor or rename later
P4
Style preference or local polish
Keep
Do not rename a local symbol if the real problem is the parent concept or boundary.
Usually omit P4 observations unless the user asks for exhaustive notes.
Output Format
For broad or thorough reviews, produce output in this structure:
Target analyzed
Boundary and system map
Observed canonical vocabulary, or proposed canonical vocabulary when supported by evidence
Naming issues found
Recommended renames, prioritized
Risks to prevent going forward
Open questions or assumptions
For narrow or quick reviews, preserve the same logic but compress the output to target analyzed, high-value naming issues, prioritized recommendations, and assumptions.
For each naming issue, include:
current name
location or scope
intended concept
why it is confusing
problem type: semantic, boundary-related, state-related, role-related, public-contract, or stylistic
evidence inspected
recommended action: keep, rename now, rename later, or monitor
For each rename recommendation, include:
proposed new name
rationale
confidence
blast radius
timing: change immediately, change when next touched, or defer
migration note when public, persisted, generated, or serialized names are involved
If there are no worthwhile renames, say so. A good name review may preserve the vocabulary and only document why it works.
Common Mistakes
Mistake
Correction
Starting with a rename list
Build the boundary and concept map first.
Renaming because a word feels generic
Prove it hides a concept, boundary, state, or responsibility.
Normalizing all synonyms
First decide whether they are truly the same concept.
Treating code as the only evidence
Include docs, tests, schemas, APIs, diagrams, issues, logs, and plans when available.
Treating the plan as automatically canonical
Compare plan and code; decide whether the plan is stale, the code is leaky, or both are valid layers.
Ignoring public contracts
Mark migration-sensitive names and avoid casual churn.
Inventing clever families
Prefer explicit, searchable, boring names that encode real distinctions.
Fixating on locals
Find the highest stable boundary that owns the concept.
Red Flags
Stop and reframe if you catch yourself saying:
"This just sounds better."
"Everything should use one term" before proving concept equivalence.
"This is only internal" without checking serialization, docs, tests, logs, or generated outputs.
"The code already knows what this means."
"The plan name must be right because it came first."
"The implementation name must be right because it exists."
"Manager/Helper/Engine is fine because it is common."
Compact Example
Issue:
current name: Job
location or scope: plan headings, jobs table, worker module, UI task list
intended concept: three concepts are using one root: durable background execution, user-visible task, and scheduled template
why confusing: future implementers may merge lifecycle state for template, queued execution, and displayed task
rationale: separates definition versus execution versus UI presentation
confidence: high
blast radius: medium if schema already exists, low if still in plan
timing: change immediately before APIs and persistence solidify
Naming rule:
Use Definition for reusable configuration, Run for one execution, and UI-specific names only at the presentation boundary. These suffixes are justified because they encode lifecycle and boundary distinctions, not decoration.
