Semantics

Concept of the skill

Semantics in software is meaning encoding: every name, status code, version number, commit type, token, telemetry attribute, tool definition, and typed value is a sign that points at a referent under a convention.

Coverage

Cross-domain semantic thinking for all naming and meaning decisions:

• Naming in code — the fundamental what + why principle, verb-prefix return/side-effect contracts (get/find/fetch/parse/ensure/assert), naming smells (Peter Hilton's seven categories), machine-reader naming smells, DDD ubiquitous language, scalar/count/collection/boolean rules
• Semantic versioning — SemVer 2.0.0 (MAJOR.MINOR.PATCH), the declared-public-API precondition, what counts as breaking, the 0.y.z initial-development rule, deprecation-as-MINOR, precedence, Hyrum's Law, SemVer vs CalVer
• Semantic commit messages — Conventional Commits format, type catalog (feat, fix, docs, style, refactor, perf, test, build, ci, chore), the spec-vs-tooling SemVer mapping, breaking-change syntax, the SemVer-from-commits automation chain
• Semantic CSS — purpose-not-appearance class names, BEM (.block__element--modifier), three-layer design-token architecture (primitive → semantic → component), the DTCG stable interchange format ($value/$type/$description/$deprecated, .tokens), cascade-layer (@layer) names and order as an explicit priority signal
• Semantic data modeling — column-naming rules (unit suffixes, boolean prefixes, timestamp/instant/date/range distinctions), semantic types beyond primitives, branded TypeScript types (string-tag and unique symbol), smart constructors, parse-don't-validate
• Semantic UI / UX — Don Norman affordances and signifiers, semantic HTML element choice (<button> vs <div onclick>, <time datetime>, lists), semantic color (with the never-color-alone rule), signifier checks, microcopy semantics
• Semantic APIs — REST resource naming (nouns + HTTP verbs, plural collections, kebab-case, max-2-nesting), HTTP status codes as semantic signals (the never-200-with-error-body rule + within-family disambiguation), RFC 9457 Problem Details for machine-readable error payloads, GraphQL naming and schema semantics (field/enum/nullability as wire contract, @deprecated, @oneOf, the media-type-dependent transport-status rule)
• Semantic tool, telemetry & schema contracts for machine readers — LLM tool/function names, descriptions as routing prompts, argument enums and units, destructive-operation legibility, result-field contracts, OpenTelemetry observability-attribute conventions, prompt-artifact boundary names, and versioning machine-read artifacts
• Universal anti-patterns — generic names, semantic drift, misleading names, appearance-based names, abbreviation ambiguity, cargo-cult naming, machine-reader drift, unit drift, enum reuse

Philosophy of the skill

Every name is a micro-decision that compounds across the codebase. A function called process(data) forces every future reader to open the implementation to understand its purpose. A design token called --light-blue breaks the moment someone adds dark mode. An API returning HTTP 200 with an error body confuses every consumer. These are not style preferences — they are semantic failures that create real debugging time and real misunderstandings.

This skill exists because naming quality degrades silently. No test catches handleRefresh() being reused for too many unrelated actions. No linter flags --big-spacing. No CI gate rejects employee2. Without explicit semantic rules loaded at decision time, agents default to the first name that compiles rather than the name that communicates. The discipline is to make meaning a first-class artifact, not a residue.

The audience for names has widened. Names are no longer read only by humans and compilers — LLM-backed routers, agents, and tool-selection layers now read tool names, function names, and field names to decide what to invoke; dashboards and alerts read telemetry attribute names no human wrote at emit time; design-token transformers and GraphQL introspection clients read names as wire contracts. An ambiguous provider or a vague process degrades automated tool selection the same way it degrades a human reader, so semantic precision is now also a machine-routing concern, not only a readability one. (For the design of the tool/function interface itself, defer to agent-engineering and tool-call-flow; semantics owns only whether the chosen words encode the right meaning.)

The mental model: a Sign (the name) acquires meaning from its Referent (what it points to) and from Convention (the shared agreement). Affordance (what the name implies you can do) is the bridge between sign and user expectation. Semantic drift happens when referents change but signs do not — a silent lie in the code, the kind no test catches.

Semantics is to code what road signage is to driving — the sign isn't the road, but bad signage causes crashes even when the road is fine.

Semantic Audit Workflow (Sign · Referent · Convention)

When auditing any name, status, version, token, schema field, tool, or signal, run the same repeatable check — it operationalizes the mental model and works across every domain in this skill:

1. Name the Sign. What is the literal signal? (process(data), 200, --light-blue, feat:, OrderId, get_user, payment.status.)
2. Find the Referent. What does it actually point at now? Read the implementation/behavior, not the name's promise. (Does process reconcile revenue? Did the request actually fail? Does the token resolve to a brand color? Can the tool delete?)
3. Check the Convention. Under the shared agreement for this artifact kind (SemVer spec, Conventional Commits, RFC 9110, DTCG, OpenTelemetry conventions, DDD ubiquitous language, the local API style), does the Sign correctly encode the Referent?
4. Predict the inference. Would a competent reader, client, design tool, router, or LLM infer the actual referent from the sign without opening implementation details?
5. Repair the mismatch. Fix the Sign, split the Referent, or update the Convention — in the same change as the behavior change so the drift never ships. A comment explaining the lie is not a semantic repair.

A mismatch at step 3/4 is semantic drift — the defect to fix.

When to Use

• Choosing semantically truthful names for variables, functions, classes, files, database columns, events, and types.
• Auditing whether a name still matches the behavior, domain concept, unit, or compatibility promise it now represents.
• Deciding whether one API name, status code, error code, field, or problem type tells the truth (route whole-surface design to api-design and protocol detail to http-semantics).
• Choosing semantic CSS classes, design-token names, or token layers that survive rebrand, dark mode, and component reuse.
• Choosing Conventional Commit type/scope or SemVer bump based on the meaning of a change.
• Modeling domain language with branded/refined types or parse-don't-validate boundaries.
• Auditing whether an LLM tool/function name, telemetry attribute, or prompt-artifact slot truthfully encodes its referent.
• Reviewing UI labels, colors, affordances, and status indicators for meaning alignment before microcopy or a11y checks.
• Reviewing code for naming quality when the problem is the meaning encoded by a name, not the mechanical rename.

Boundary Routing

1. Semantic Naming in Code

The Fundamental Principle

A name must encode what something is, why it exists, and what contract it exposes to readers or tools. The reader should not need to open the implementation to distinguish the domain concept, unit, side effect, lifecycle state, or compatibility signal.

Rules

Verb Prefixes Encode a Return/Side-Effect Contract

A function's leading verb is a promise about its return shape, cost, certainty, and side effects; readers and callers (human and LLM) route on it. Keep the verb honest:

The prefix is the at-a-glance signal; when behavior and prefix disagree, the prefix lies and every caller inherits the wrong expectation. (When the work becomes artifact-specific casing, prefix/suffix policy, or rename mechanics, route to naming-conventions.)

Naming Smells (Peter Hilton's catalog)

1. Meaningless — foo, bar, tmp, x
2. Abstract — data, object, thing, item
3. Numeric suffixes — employee2 hides the distinction
4. Abbreviations — acc (accumulator? accuracy? account?)
5. Vague verbs — get, process, handle, manage say nothing about behavior
6. Type-encoded — array, string, int as variable names
7. Weasel suffixes — Info, Data, Manager, Helper, Utils, Base, Entity

Machine-Reader Naming Smells

Names are now read by LLM routers, tool selectors, schema validators, design-token transformers, GraphQL introspection clients, and changelog generators. This adds several smells beyond Hilton's:

DDD Ubiquitous Language

Core domain classes (entities, value objects, events, services) must use business terminology. Zero tolerance for weasel words. Technical terms are acceptable only in infrastructure classes where no domain equivalent exists.

Translation tax: every time a developer mentally translates between code vocabulary and business vocabulary, cognitive overhead accumulates — and it compounds across teams and codebase lifetime.

2. Semantic Versioning (SemVer 2.0.0)

Format: MAJOR.MINOR.PATCH

What Constitutes a Breaking Change

• Removing a public method, class, endpoint, or field
• Changing return types or parameter types
• Changing default behavior users depend on
• Renaming public APIs without aliases
• Changing serialization format
• NOT breaking: adding optional params, new endpoints, new types

SemVer Nuances Agents Often Miss

• SemVer requires a declared public API. If the public API is vague, the version number cannot communicate compatibility truthfully — declare the surface before applying the rules.
• `0.y.z` is initial development (SemVer §4): anything MAY change at any time; the public API is not considered stable. Do not read a 0.4 → 0.5 bump as a "safe minor" — many ecosystems (npm by default) treat a 0.y.z MINOR bump as potentially breaking. Version 1.0.0 is what declares a stable public API; it is a semantic commitment, not a maturity badge.
• Deprecating public-API functionality requires a MINOR bump — deprecation is a forward-compatibility signal even before removal. Removing or renaming public API without an alias is MAJOR.
• Precedence: a pre-release version has lower precedence than its normal version (1.0.0-rc.1 < 1.0.0), and build metadata (1.0.0+20130313144700) is ignored when determining precedence (SemVer §11). A release candidate never accidentally outranks the final release; never use build metadata to signal compatibility.
• Hyrum's Law caveat: at sufficient scale, all observable behavior of an API becomes something some consumer depends on, even behavior the written contract never promised. A bug-fix that changes observed output can break real consumers — weigh that before calling it a safe PATCH.

Pre-release tags

1.0.0-alpha.1, 1.0.0-beta.2, 1.0.0-rc.1

SemVer vs CalVer

3. Semantic Commit Messages (Conventional Commits)

Format: type(scope): description

Spec Meaning vs Release-Tool Policy

Only three mappings are normative. Conventional Commits 1.0.0 assigns a SemVer effect to exactly three things: fix → PATCH, feat → MINOR, and a breaking change (! or BREAKING CHANGE: footer) → MAJOR. Every other type is allowed but carries no implicit SemVer effect unless your release tooling defines one (spec §"Summary" + the SemVer-relationship FAQ). The † rows above therefore depend on local configuration: many tools bump nothing for perf/refactor/docs by default, while some configs map perf → PATCH. Do not assert "perf is a PATCH bump" as a property of the spec — it is a property of a particular tool's config.

If one change honestly needs multiple types, split the commit whenever possible so the type remains a truthful signal. If it cannot be split, choose the type that communicates the externally observable change, then use the body/footer for secondary facts.

Breaking changes — add ! after the type/scope or a BREAKING CHANGE: footer → MAJOR bump. The footer token must be uppercase BREAKING CHANGE (or BREAKING-CHANGE); a lowercased "breaking change" is not recognized by tooling. ! and the footer may be used together — the ! is the at-a-glance signal, the footer carries the migration detail.

feat(auth)!: replace session tokens with JWT

BREAKING CHANGE: Session-based auth removed. All clients must use Bearer tokens.

Automation chain: Conventional Commits → semantic-release → changelog → publish. Fully automated versioning from commit messages. This is the concrete reason the type choice is semantic, not cosmetic: a feature mislabeled chore is silently dropped from the changelog and never triggers the MINOR bump it earned.

4. Semantic CSS

Class Names Describe Purpose, Not Appearance

BEM: .block__element--modifier

Names encode component structure. .card__title belongs to .card without reading HTML.

Design-Token Naming: Three-Layer Architecture

/* Layer 1: Primitive (raw values, no meaning) */
--blue-500: oklch(0.62 0.18 260);
--spacing-4: 1rem;

/* Layer 2: Semantic (purpose-driven) */
--color-text-primary: var(--grey-900);
--color-bg-danger: var(--red-100);
--spacing-component-gap: var(--spacing-4);

/* Layer 3: Component (scoped to specific component) */
--button-bg-hover: var(--color-bg-interactive-hover);
--card-border-radius: var(--radius-md);

Rule: UI code references semantic tokens. Semantic tokens reference primitives. Primitives hold raw values. Never skip a layer.

Anti-patterns: --light-blue (breaks on rebrand), --color-1 (meaningless), --homepage-hero-cta-bg (too coupled to one location).

The DTCG interchange format (stable Final Report, 2025.10)

The three-layer architecture above is the authoring discipline; the Design Tokens Community Group (DTCG) format is the vendor-neutral interchange format that lets that discipline travel between tools (Figma, Style Dictionary, Tokens Studio, etc.). It reached its first stable version — a Final Community Group Report, 2025.10, on 2025-10-28 (stable, but explicitly not a W3C Standard); the skill previously cited a /drafts/ URL, which is now superseded. Semantic primitives that matter for naming and meaning:

{
  "color": {
    "text-primary": { "$value": "{grey.900}", "$type": "color", "$description": "Default body text" }
  }
}

• Aliasing is what makes appearance-coupled names wrong — the reference syntax lets one semantic token (--color-bg-danger / color.status.danger.bg) resolve to different primitive values under different themes, so a name baked to one appearance (--light-blue) cannot follow a theme switch. If color.status.success.bg aliases green today and blue tomorrow, the semantic token survives a rebrand because the sign's purpose stayed stable.
• File convention: .tokens / .tokens.json, media type application/design-tokens+json.
• Treat richer theming and specific color-space support (OKLCH / Display-P3 / CSS Color 4) as the consuming tool's capability layered on the format, not as a guarantee the format spec itself makes — verify against the tool you target. For token taxonomy, component APIs, theming governance, and migration, route to design-system-architecture / theme-system-design; semantics owns only whether the names and aliases preserve intended meaning.

Cascade Layers (@layer) — the layer name and order are a priority signal

CSS cascade layers (CSS Cascade Level 5) let you name groups of rules and declare their precedence explicitly, independent of source order or selector specificity. Both halves are semantic — semantics owns only the meaning of the layer names and the priority signal, not selector specificity, @scope, or full cascade mechanics (route those to CSS-architecture / frontend skills):

/* The order statement IS the contract: later layers win. */
@layer reset, base, components, utilities;

@layer components { .card { padding: 1rem; } }
@layer utilities  { .p-0  { padding: 0; } }   /* wins over components, despite equal specificity */

• *The layer name encodes intent (`reset` / `base` / `theme` / `components` / `utilities`) the same way a semantic token name does — `@layer hacks` or `@layer z1` is the appearance-named `--light-blue` of the cascade: it says nothing about why* its rules should win.
• The `@layer name, name, …` statement encodes priority — reordering it silently changes which rules win across the whole sheet, with no selector change. Treat that order as a published contract; a reorder is a behavioral change, not a cosmetic one.
• Layer contents must match the layer's promise — component one-offs accumulating inside a tokens layer is layer drift; move the rule to its owning layer.
• Unlayered styles outrank every layer, so "drop it outside a layer to force it to win" is a meaning-defeating escape hatch; an overrides layer should be rare and justified — prefer fixing the owning layer or layer order.

5. Semantic Data Modeling

Column-Naming Rules

Unit and Temporal Naming

Numbers and timestamps are the places where syntax most often lies — a bare type passes every check while the meaning is wrong:

Semantic Types (Beyond Primitives)

A raw string can hold an email, URL, SQL query, or credit-card number — semantically different despite identical type. Semantic types make illegal states unrepresentable:

Branded Types in TypeScript

TypeScript is structurally typed: two strings are interchangeable no matter what they mean. A brand adds a phantom, compile-time-only tag so the type system treats OrderId and UserId as distinct. Prefer a reusable helper and a parser/constructor boundary; two brand forms, chosen by stakes:

// Form A — string-tag brand. Covers most app code; one reusable helper.
type Brand<T, Tag extends string> = T & { readonly __brand: Tag };
type OrderId = Brand<string, 'OrderId'>;
type UserId  = Brand<string, 'UserId'>;

function getOrder(id: OrderId): Order { /* ... */ }
getOrder(userId); // Compile error: UserId is not assignable to OrderId

// Form B — unique symbol brand. For libraries / high-stakes domains:
// the tag cannot be forged or collided with from another module.
declare const OrderIdBrand: unique symbol;
type OrderId2 = string & { readonly [OrderIdBrand]: true };

Smart constructor over raw cast. A brand only guarantees distinctness, not validity. Mint branded values through a validating constructor so the cast happens in exactly one audited place — this is the brand's bridge to parse-don't-validate below:

function parseOrderId(input: string): OrderId | null {
  return /^ord_[0-9a-f]{16}$/.test(input) ? (input as OrderId) : null;
}

Rules:

• Brand only values where mixups are plausible and costly: IDs, units, money, URLs, emails, permission scopes, state-machine states.
• Mint branded values at a parser or smart constructor, not by scattering raw casts at call sites.
• Gotcha: the brand is a compile-time fiction. The phantom property does not exist at runtime — never write if (value.__brand === 'OrderId'); it is always undefined. Runtime checks belong in the smart constructor.
• For soundness, narrowing, exhaustiveness, validator choice, and runtime-boundary mechanics, route to type-safety; semantics owns only when a type/brand/unit name encodes the wrong meaning.

Parse, Don't Validate

Instead of checking data after the fact, parse it into a type that guarantees validity:

// Bad: validate then trust
function processEmail(input: string) {
  if (!isValidEmail(input)) throw new Error('Invalid email');
  sendEmail(input); // input is still just string
}

// Good: parse into semantic type
function parseEmail(input: string): Email | null {
  return isValidEmail(input) ? (input as Email) : null;
}

The core idea: preserve the knowledge the parser gained in the type, instead of discarding it after a boolean check and re-validating downstream. A parseEmail that returns Email | null pushes the "is this valid?" question to the boundary once; everything past the boundary holds a value whose type already proves validity.

6. Semantic UI / UX

Affordances and Signifiers (Don Norman)

• Affordance — what an object allows you to do (a button affords pressing)
• Signifier — what communicates the affordance (the button's raised appearance, shadow, cursor change)

Semantic UI ensures signifiers match affordances: clickable things look clickable, draggable things look draggable, disabled things look disabled.

Semantic HTML — the element choice is the first signal

The HTML element you pick is a meaning declaration, read by browsers, assistive tech, and crawlers before any class or label. A <div onclick> styled to look like a button is the markup equivalent of process(data): it works mechanically but encodes none of the meaning.

Rules:

• Choose the element whose native meaning matches the referent before adding ARIA or JavaScript behavior.
• Class names should describe the nature of the content or component role, not only the desired presentation.
• Do not derive business meaning from opaque id values; use explicit data fields or structured attributes when meaning must be machine-readable.
• *Verifying the resulting accessibility contract — roles, focus order, screen-reader announcement, `aria- — belongs to a11y.** Semantics flags the <div>-that-should-be-a-<button>`; a11y proves the fix is actually accessible.

Semantic Color

Rule: color must never be the sole differentiator. Always pair with icon, text, or shape. (The color-redundancy rule is a semantic-signal rule that also reaches terminal output, logs, and data viz — not only product UI.)

Signifier Checks

Semantics can flag when a UI signal lies; semiotics and a11y own the deeper checks:

Microcopy Semantics

• Button labels — verbs with clear objects: "Save changes" not "Submit"
• Error messages — name what broke + how to fix: "Password must be 8+ characters" not "Invalid input"
• Confirmations — name what will happen: "Delete 3 orders permanently?" not "Are you sure?"
• Empty states — explain value + provide action — not just "No data"

For the full UX-text pattern catalog (button label rules, empty-state structure, tooltip rules, dialog rules, toast rules), use the dedicated microcopy skill — semantics owns only the underlying meaning rule.

7. Semantic APIs

For the whole API surface (resources, schemas, pagination, idempotency, versioning, auth, error-envelope design) use api-design; for RFC-level method/status/header/cache detail use http-semantics. Semantics owns whether a specific name, status, field, or error signal tells the truth.

REST Resource Naming

HTTP Status Codes as Semantic Signals

Do not report a failed HTTP request as 200 merely because the transport succeeded. RFC 9110 defines 200 as request success; if the request failed, the status code should carry that failure class. Domain-level partial success can still use a typed success payload when the request itself truly succeeded.

Choosing which code is itself a semantic decision — these distinctions carry meaning consumers act on:

Machine-readable error bodies — RFC 9457 Problem Details

A correct status code tells the client which class of failure occurred; the body should tell it what specifically went wrong, in a structured, predictable shape — not an ad-hoc { "error": "..." } invented per endpoint. *RFC 9457 Problem Details for HTTP APIs* (July 2023, Standards Track; obsoletes RFC 7807) is the vendor-neutral standard for that body. Media type application/problem+json**; the object's reserved members are semantic:

{
  "type": "https://example.com/probs/insufficient-funds",
  "title": "Insufficient funds",
  "status": 402,
  "detail": "Account 12345 has a balance of 30, but the order total is 50.",
  "instance": "/orders/9001"
}

• type — a URI identifying the problem class (stable, dereferenceable, the machine key clients branch on).
• title — short human-readable summary of the problem class (does not change per occurrence).
• status — the HTTP status code, duplicated in-body so it survives proxies/logging; must match the actual response status when present.
• detail / instance — explanation and identifier for this specific occurrence; detail is human-facing and should not be parsed for structured data. Typed extension members carry problem-specific structured data such as validation pointers.

RFC 9457 added (over 7807) explicit guidance for representing multiple problems (e.g. several field-validation errors via an errors extension) and a shared registry of problem types; when different problem types compete, represent the most relevant/urgent one rather than a vague batch envelope. The semantic rule: the status code is the class signal, the type URI is the machine-readable specific signal, and title/detail are the human signal — keep all three aligned, never contradicting.

GraphQL Naming

• Types: PascalCase (Order, LineItem)
• Fields: camelCase (totalRevenue, createdAt)
• Mutations: verb + noun (createOrder, updateShippingAddress)
• Enums: SCREAMING_SNAKE (ORDER_STATUS, PAYMENT_METHOD)

GraphQL Schema Semantics (the names are the contract)

In GraphQL the schema is introspectable and there is no URL versioning, so every name is a published wire contract that clients have already baked in. The meaning-encoding rules go beyond casing:

• Field and argument names are the API. A client selects order { totalRevenue } by exact name; renaming totalRevenue → revenue is a breaking change for every consumer even though no endpoint moved. There is no path to deprecate via a new route — see @deprecated below.
• Enum values are stable wire vocabulary, not labels. PAYMENT_METHOD values travel literally over the wire and are persisted by clients. Renaming CREDIT_CARD → CARD silently breaks any client that stored or branches on the old value. Add a new value; never repurpose an existing one (that is semantic drift on a value clients already trust).
• Deprecate, don't delete: `@deprecated(reason: "…")`. The directive is the semantic migration signal — it keeps the field introspectable and tells tools/humans what to use instead. A reason that just says "deprecated" wastes the one machine-readable channel you have; name the replacement.
• Nullability is a meaning claim. String! (non-null) promises the field is always present; String admits null. Loosening String! → String is breaking (clients no longer get the guarantee); tightening String → String! is breaking the other way. The ! encodes a contract, not a style preference.
• `@oneOf` input objects encode "exactly one of these fields" at the type level — a semantic constraint (mutually-exclusive variant) made checkable instead of left to prose. Reach for it when an input is a tagged union, not a bag of optional fields.
• Field order in the SDL is not semantic (selection is by name), but stability of it aids diffs — do not rely on order to carry meaning.

The transport-status rule for GraphQL depends on the media type — it is NOT "errors always ride a 200." Under the legacy application/json response media type, a well-formed GraphQL response (data and/or errors) is returned with 200, because the HTTP request itself succeeded and the failure lives in the errors array of the envelope. Under the newer application/graphql-response+json media type (GraphQL-over-HTTP), the server should use the HTTP status to reflect the outcome: a request error (the request could not even be parsed/validated, so no well-formed GraphQL response can be produced) yields a non-2xx status such as 400, while a field/execution error (a valid request whose resolver failed) still returns 200 with errors populated. The correct generalization: the status reflects whether a well-formed GraphQL response could be generated, and the errors array reflects per-field execution outcomes. This refines — does not contradict — the REST never-200-with-error rule, and is not an excuse for a REST API to report a failed request as 200.

8. Semantic Tool, Telemetry & Schema Contracts for Machine Readers

The Philosophy section noted that LLM routers, tool-selectors, dashboards, and introspection clients now read names to decide what to invoke or how to join data. This section is the meaning-encoding rules for that audience. (The design of the tool surface — which tools to expose, granularity, statefulness, orchestration — belongs to agent-engineering / tool-call-flow; telemetry strategy belongs to observability-modeling. Semantics owns only whether the chosen words and shapes encode the right meaning.)

A function/tool definition (OpenAI function calling, the MCP tools contract, an LLM structured-output schema) is read by a model the same way a human reads an identifier: the model has only the names, descriptions, and types — it never sees the implementation. Every field is a routing signal, and a misleading one causes the model to call the wrong tool or fill the wrong argument. Strict/typed schemas constrain shape; they do not guarantee semantic truth — a schema can be valid while amount means cents in one tool and dollars in another.

The unifying rule: a machine reader acts on the signal with no recourse to implementation or tribal context, so a name or schema field that misleads it is a behavioral defect — identical in kind to a misleading identifier, just with a model instead of a developer as the misled party. Destructive boundaries must be legible in the contract. If a tool deletes, charges, sends, or otherwise mutates the world irreversibly, the name and description must say so (delete_*, send_*, "permanently removes…"). MCP surfaces this as a destructiveHint annotation; the semantic rule holds regardless of transport. As with GraphQL enums, renaming or repurposing an enum value the model has learned to emit (or that downstream code persists) is a breaking change, not a cosmetic one.

Observability attributes are wire vocabulary too (OpenTelemetry Semantic Conventions)

Telemetry attribute names are read by dashboards, alerts, and queries that no human wrote at emit time — so they are a machine-read contract with the same drift hazard as a tool schema. OpenTelemetry Semantic Conventions publish a standardized vocabulary (http.request.method, http.response.status_code, url.full, db.system, service.name, error.type, …) precisely so a span from one service joins a query from another without per-team translation.

• Prefer the standardized attribute name over a hand-rolled one. Emitting method or httpMethod instead of http.request.method forks the vocabulary — every downstream query must special-case your spelling, the cross-service join breaks, and the "translation tax" from §1 reappears at the observability layer.
• Attribute names are stable wire keys, not labels. Renaming http.method → http.request.method (a real OTel stabilization) breaks every saved query and alert keyed on the old name — treat it as breaking, the same as renaming a GraphQL field or a persisted enum value.
• Use dot-delimited namespaces and snake_case name components when authoring OpenTelemetry-style custom attributes; the dotted prefix declares the attribute's domain (http. is a transport signal, not a domain status). For span boundaries, signal selection, sampling, dashboards, and SLOs, route to observability-modeling.

Prompt-artifact boundary names

Prompt templates, agent instructions, and eval prompts also expose semantic surfaces: file/module names, section headings, XML/Markdown tags, placeholders, typed input parameters, expected-output labels, rubric field names, and eval IDs. Semantics can audit whether those signs match their actual role:

Do not import prompt-engineering strategy or a normative "SemVer for prompts" rule here. As prompts and agent configs become deployed artifacts, applying SemVer semantics to them is an emerging convention (not a published standard): treat a change to the expected input/output schema or a removed capability as MAJOR, an added capability or new optional input as MINOR, and a wording/clarity fix that preserves the contract as PATCH — but record the actual mapping you use; do not present it as spec-defined. Semantics owns only whether names, sections, variables, and output fields tell the truth.

9. Universal Anti-Patterns

Source Notes

• Fowler's Ubiquitous Language article grounds the domain-language rule: terms used by developers and domain experts must be rigorous enough for software because ambiguity turns into design defects.
• Hilton's naming-smells catalog grounds the smell list and the default remediation: rename when a name is meaningless, abstract, numeric-suffixed, abbreviated, vague, type-encoded, or simply wrong.
• SemVer and Conventional Commits ground compatibility signaling: version bumps and commit types communicate machine-readable change meaning, not decoration. The 0.y.z carve-out (§4 of the SemVer spec) grounds the "pre-1.0 promises nothing" rule; the SemVer FAQ + Hyrum's Law ground the warning that observed behavior can become a de facto contract. The Conventional Commits spec grounds the correction that only feat/fix/breaking carry a spec-defined SemVer effect — other types' bumps are tooling configuration.
• The GraphQL specification grounds GraphQL schema semantics (names/enums/nullability as published contract, @deprecated, @oneOf); the GraphQL-over-HTTP spec grounds the media-type-dependent transport-status rule (request errors vs field errors). The OpenAI function-calling guide and the MCP tools specification ground the tool/schema-contract section: names, descriptions, argument enums/units, and destructive hints are the signals a model routes on.
• RFC 9110 grounds HTTP status codes as semantics for request outcome and within-family choice; RFC 9457 (obsoleting RFC 7807) grounds the structured, machine-readable error-body shape (application/problem+json: type/title/status/detail/instance, multi-problem representation, problem-type registry) that the status code's class signal points into.
• The Design Tokens Community Group format (stable Final Report 2025.10, not a W3C Standard) grounds tokens as named values with $value/$type/$description/$deprecated and {alias} references; the format standardizes the token/group/alias/type shape (and explicitly warns tools not to infer type or purpose from group names), and the semantic-token purpose layer is the authoring discipline built on top. Richer theming and color-space support are properties of the consuming tool, not guarantees of the format spec.
• CSS Cascading and Inheritance Level 5 (cascade layers) grounds the @layer rule: the layer name encodes rule-group intent and the layer-order statement encodes precedence explicitly, so reordering layers is a behavioral change, not a cosmetic one; selector specificity and @scope mechanics stay with CSS-architecture skills.
• The HTML Living Standard's element semantics ground the semantic-HTML rule: the chosen element (<button>, <a>, <nav>, <main>, <time>, <ul>) is itself a meaning declaration read by browsers and assistive tech; semantics flags the wrong element, and a11y verifies the resulting accessibility contract.
• OpenTelemetry Semantic Conventions (and the naming rules) ground the observability-attribute rule: standardized, namespaced, snake_case attribute names are a machine-read contract joined across services, so preferring the standard name, avoiding namespace squatting, and treating renames/reuse as breaking is the same wire-vocabula