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