Reviews and improves naming quality for data models (types, structs, classes, interfaces, enums, fields, properties) and functions (methods, procedures). Use when the user wants to review, audit, improve, or fix naming in their codebase — including type names, function names, variable names, field names, or any identifier naming. Also trigger when the user asks about naming conventions, naming anti-patterns, naming smells, wants better names for their models or functions, or says "naming review", "review naming", "name review", "audit names", "improve naming", "bad names", "naming conventions", "rename identifiers", "clean up names". Covers clarity, honesty, domain alignment, consistency, language-specific conventions, and common anti-patterns like Manager/Handler/Helper classes, Data/Info suffixes, type encoding, lying names, and vague verbs. Includes automated detection via scripts/naming-smells.sh and linter integration for Go (revive), TypeScript (eslint naming), Rust (clippy), and Python (ruff).
Reviews and improves naming quality for data models (types, structs, classes, interfaces, enums, fields, properties) and functions (methods, procedures). Use when the user wants to review, audit, improve, or fix naming in their codebase — including type names, function names, variable names, field names, or any identifier naming. Also trigger when the user asks about naming conventions, naming anti-patterns, naming smells, wants better names for their models or functions, or says "naming review", "review naming", "name review", "audit names", "improve naming", "bad names", "naming conventions", "rename identifiers", "clean up names". Covers clarity, honesty, domain alignment, consistency, language-specific conventions, and common anti-patterns like Manager/Handler/Helper classes, Data/Info suffixes, type encoding, lying names, and vague verbs. Includes automated detection via scripts/naming-smells.sh and linter integration for Go (revive), TypeScript (eslint naming), Rust (clippy), and Python (ruff).
A comprehensive review skill for making identifiers — especially data model names and function names — honest, clear, and domain-aligned. Based on Clean Code principles, Domain-Driven Design, and analysis of naming anti-patterns across production codebases.
Process
READ, UNDERSTAND, RESEARCH, REFLECT before each action.
Step 0: Run Automated Detection
Before manual review, run automated tools to surface low-hanging fruit. Don't reinvent what linters already do well.
Run the appropriate linters for the project's language:
Then run scripts/naming-smells.sh for deeper pattern detection that linters miss (vague nouns, Manager/Handler classes, Impl suffixes, split-brain terminology). This surfaces issues that require human judgment.
Find all source files in the target scope. Read every file that defines data models or functions. Understanding the full picture is essential for catching cross-cutting issues like inconsistent naming patterns, duplicated concepts under different names, and split-brain terminology.
Identify the primary language(s) — conventions differ by language and this skill adapts accordingly.
Exclude from review: Generated code (protobuf, OpenAPI/Swagger, ORM models, graphql-codegen, TypeSpec output). These names are dictated by schemas or external tools — flagging them wastes time. If generated names are bad, fix the source schema or generator config, not the output.
Step 2: Build Naming Glossary
Before checking individual identifiers, build a glossary of all type names and their relationships. This reveals split-brain terminology at a glance.
Extract all type/function names and group by domain:
# Naming Glossary## Domain: User Management
| Code Name | Role | Potential Split-Brain |
| ------------- | ---------------- | ------------------------ |
| User | Type (struct) | |
| Customer | Type (struct) | ← same as User? |
| Client | Type (interface) | ← same as User/Customer? |
| AccountHolder | Type (struct) | ← same as User? |
| getUser | Function | |
| fetchCustomer | Function | ← same as getUser? |
| findClient | Function | ← same as getUser? |
When multiple names appear to represent the same domain concept, flag them for reconciliation. The glossary becomes the authoritative reference for the rest of the review.
Step 3: Categorize
Classify each identifier into its role:
Category
Examples
Types
structs, classes, interfaces, enums, type aliases
Functions
methods, functions, procedures, constructors
Fields
struct fields, class properties, object attributes
Variables
local variables, parameters, constants
Packages/Modules
package names, module names, namespace names
Step 4: Review Against Checklist
For each identifier, check ALL categories below. Read references/common-naming-problems.md for detailed explanations and fixes of each issue.
Honesty — Does the name tell the truth?
No lying names — the name must describe what the thing actually does or represents
No hidden side effects — a function named getX must not mutate state
No misleading scope — a name like ProcessEverything on a function that only handles one case
No euphemisms — sanitize for delete, adjust for truncate
Clarity — Can a newcomer understand the name without asking?
No unpronounceable names — if you can't say it in a code review, rename it
No abbreviations that aren't universal — usr, cnt, calc, mgr are not universal
No single-letter names — except accepted loop variables (i, j, k) or math context (x, y, z)
No number suffixes — user1, user2, result2 indicate missing abstractions
No cryptic prefixes/suffixes — Hungarian notation (strName, iCount, m_user) encodes type information that the type system already knows
Precision — Does the name distinguish from alternatives?
No vague nouns — Data, Info, Record, Item, Object, Thing carry no domain meaning
No vague verbs — do, handle, process, manage, perform say nothing about what actually happens
No "Manager/Handler/Processor/Helper/Util/Utility" classes — these are trash-can names that collect unrelated behavior; split by responsibility
No redundancy with context — User.userName, Customer.customerEmail, Exception.exceptionMessage
No redundancy with type — nameString, amountDecimal, idGuid — the type already says this
Domain Alignment — Does the name speak the domain language?
Uses ubiquitous language — names reflect the domain experts' vocabulary, not developer jargon
No mixed metaphors — same concept called Customer in one place, Client in another, AccountHolder in a third
No split-brain terminology — two names for the same domain concept (e.g., Order vs Purchase vs Transaction for the same thing)
No technical jargon for domain concepts — AggregateRoot, DTO, Entity in the name when the domain term is Invoice, Payment, Shipment
Implementation Leakage — Does the name expose how instead of what?
No "Impl/Concrete/Default" suffixes — these leak architecture; use domain names (InMemoryPaymentGateway is OK, PaymentGatewayImpl is not)
No "I" prefix for interfaces — except C# convention; in Go/TypeScript/Rust/Python, IUserService is an anti-pattern
No framework leakage — RestController, JpaEntity, SqlRepository when the domain term is CustomerService, Order, ProductCatalog
Boolean Naming — Are yes/no questions phrased as questions?
Boolean fields read as yes/no — isActive, hasPermission, canWrite, shouldRetry
No negative booleans — isNotEnabled → isDisabled, hasNoItems → isEmpty
No ambiguous booleans — status (what kind?), flag (which flag?), check (checks what?)
Functions returning bool are questions — isValid(), hasAccess(), canProceed()
Function Naming — Do function names reveal intent?
Functions are verbs or verb phrases — calculateTotal, sendEmail, validateOrder
Command-Query Separation — commands change state (verbs: add, remove, send), queries return data (nouns/questions: total, isValid)
No and/or in function names — addAndValidate does two things; split into add + validate
No arbitrary comments in names — processOrderV2, handleRequest_new, calculateTax_fixed
Factory functions describe what they create — NewOrder() not Create(); withDiscount() not apply()
Consistency — Is the same thing called the same thing everywhere?
No synonym inconsistency — delete/remove/destroy/erase for the same operation across the codebase
No inconsistent verb tense — getUser/fetchUser/retrieveUser/queryUser for the same operation
Consistent naming within a domain — if you name one createX, name them all createY, not makeY or newY
No cutesy/clever names — reaper, ninja, wizard, magic obscure meaning
Language-Specific Conventions
Go: CamelCase (exported), camelCase (unexported); interfaces without I prefix; Err prefix for errors; New for constructors
TypeScript: PascalCase for types/interfaces/classes; camelCase for functions/variables; no I prefix for interfaces
Rust: SnakeCase for functions/variables; CamelCase for types/traits; no I prefix for traits
Python: snake_case for functions/variables; PascalCase for classes; no I prefix for ABCs
Java/C#: PascalCase for classes/methods; camelCase for fields/variables; I prefix only in C# for interfaces
Step 5: Generate Report
Write a self-contained styled HTML report — not a flat Markdown file. A naming review
is a point-in-time audit with category-colored issue tables that benefit from visual treatment.
The reason behind each naming rule matters more than the rule itself. A review that explains "why" is far more valuable than one that just says "rename this." When reporting issues, always include:
What the issue is
Why it matters (readability, maintainability, domain alignment, honesty)
What to call it instead (concrete suggestion with reasoning)
Severity Guide
Severity
Meaning
🔴 Critical
Name lies about behavior (hidden mutation, misleading scope)
🟠 High
Name carries no meaning (Data, Info, Handler, Manager, do, process)
🟡 Medium
Name is unclear or inconsistent (abbreviations, synonym drift, tense mismatch)
🔵 Low
Style or convention issue (casing, minor redundancy, language-specific norms)
References
references/common-naming-problems.md — Detailed catalogue of naming anti-patterns with before/after examples, organized by category
references/naming-best-practices.md — Ideal naming patterns per category, domain-driven design language guidelines, and language-specific conventions
scripts/naming-smells.sh — Automated detection of naming anti-patterns using grep/ripgrep
Read these files when you need specific examples or deeper guidance on a particular issue category.
Related Skills
full-code-review — Broader code review that includes naming as one aspect. Use naming-review when you want focused, deep naming analysis
code-quality-scan — Runs linters that already catch some naming issues. naming-review goes deeper into semantics linters can't check
deduplicate-code — Finds code duplication which often reveals split-brain naming (same concept, different names)
architecture-review — Architecture issues often manifest as naming problems (Manager classes, Impl suffixes)
Execution
READ, UNDERSTAND, RESEARCH, REFLECT.
Break this down into multiple actionable steps. Think about them again.
Execute and Verify them one step at the time.
Repeat until done. Keep going until everything works and you think you did a great job!
