Linguistics

Linguistics

Concept of the skill

Treat every name or visible string as a small language artifact. Its form carries a contract: morphology makes the artifact parseable, semantics fixes what it means, pragmatics fits the situation, and register fits the audience.

This skill replaces taste-based naming and copy decisions with repeatable linguistic checks. It prevents weak contracts such as generic handlers, unqualified polysemous identifiers, utility-file dumping grounds, agent-register UI copy, blame-heavy errors, and culturally narrow language that does not translate cleanly.

Distinct from naming-conventions, which owns artifact-specific casing and deterministic convention policy. Distinct from refactor, which owns behavior-preserving rename mechanics across call sites. Distinct from information-architecture, which owns document, navigation, and content-structure findability. Distinct from microcopy, which owns specialized UI-text pattern catalogs. Distinct from writing-humanizer, which owns prose polish, AI-tell removal, and rhythm repair. Linguistics in software is grammar for the interface between people and systems: the syntax of a name or sentence should make the intended meaning easy to recover without hidden context. The common mistake is treating naming and wording as personal preference. Ambiguous words, weak compounds, blame-heavy error text, and wrong register create predictable comprehension failures; agreement inside one team does not make the language portable or clear.

Coverage

Linguistic analysis patterns for software work — the rules that govern how names, labels, error messages, and copy are formed. Covers (1) morphology: casing conventions per artifact kind, compound-word head-first ordering, abbreviation decision tree, verb-noun naming patterns; (2) polysemy resolution: identifying ambiguous identifiers in a codebase and qualifying them with their domain (e.g., provider → fulfillmentProvider / authProvider / paymentProvider); (3) register selection: choosing the right tone, vocabulary, and sentence structure for end-users, agents, and developers; (4) error-message linguistics: the three-part What → Why → What-to-do structure with blame-free framing, specificity rules, and actionability; and (5) cross-cultural linguistic awareness: the linguistic facts (number structure, currency notation, grammatical gender, script direction) that shape internationalization decisions. Provides the linguistic rationale for these choices — not the casing convention itself, not document/navigation structure, not specialized UI microcopy pattern catalogs, not final prose polish, not canonical term definition, and not i18n implementation.

Philosophy of the skill

Language in software is architecture. A function named handleContinue can do anything from persisting form state to advancing a wizard — it carries a weak contract outside its local component. A function named transformPaymentEvent is much harder to misunderstand. An error message that says "Error 500" transfers zero information; one that says "Order sync paused — your API key may have expired. Open Settings → Integrations to reconnect." transfers a complete causal chain plus an action. The same word can carry different meanings in different parts of the same codebase, and without disambiguation every reader must infer the meaning from surrounding context — that inference has a cost, and sometimes a failure mode.

Three linguistic laws follow:

1. Names are contracts. A name commits to what a thing is and what it does. Changing behavior without changing the name is a lie.
2. Ambiguous terms compound. One ambiguous term causes one bug. Ten ambiguous terms cause a combinatorial fog. Resolve at the first encounter, not in a later cleanup.
3. Audience determines form. The same fact needs different words for an end-user, an agent, and a developer. Writing in the wrong register is a communication failure even when the facts are correct.

The linguistic goal is to make meaning unambiguous at the point of contact — in the name itself, the message itself, the label itself — not in a glossary entry the reader has to look up.

Boundary Routing

1. Naming Precision (Morphology)

Morphology is the study of word form — how words are built from parts. In code, the "words" are identifiers, and the "morphology rules" are casing conventions, compounding strategies, and abbreviation policies.

Casing Conventions and Their Linguistic Basis

Rule: match the convention to the artifact-kind context, never cross-pollinate. orderCount in TypeScript, order_count in SQL, order-count in CSS. They are the same concept expressed in three linguistic registers. The casing decision itself belongs to naming-conventions; this skill explains why each convention fits its context.

Compound Word Rules

Compound words carry more semantic load than simple words. The order of morphemes matters.

Head-first vs. modifier-first:

In English technical compounds, the modifier comes first and the head (the main concept) comes last. The head tells you what kind of thing it is; the modifier qualifies it.

Anti-pattern: reversing the order (costShipping, countOrders) breaks English morphology and makes names harder to scan. The mind expects the head at the end.

Disambiguation through compounding:

When a simple word is ambiguous, compound it with its domain qualifier:

Rule: if a word has more than one meaning anywhere in the codebase, compound it with its domain qualifier. The unqualified form is banned in typed code.

Abbreviation Policy

Abbreviations save characters but cost comprehension. Use this decision tree:

Is this abbreviation universally understood by every reader?
├── Yes → Allow (examples: URL, API, DB, ID, HTML, CSS, JSON, HTTP, SKU)
└── No → Is the full form longer than 25 characters?
    ├── No → Use the full form
    └── Yes → Is the abbreviation used in 10+ places?
        ├── No → Use the full form, consider renaming the concept
        └── Yes → Define the abbreviation in the project glossary, then allow it

Always acceptable: id, url, api, db, html, css, json, http, sku, ui, ux, pii, gdpr.

Never acceptable: mgr (manager), proc (process or procedure?), calc (just write calculate), btn (button), val (validate or value?), auth without qualifier (authentication or authorization?), temp (temporary or temperature?), util (a red flag — see anti-patterns).

Verb-Noun Naming Patterns

Functions describe actions (verbs). Variables describe things (nouns). Mixing the patterns creates naming smells.

Function naming — verb-first:

Anti-pattern: using handle for everything in server-side or utility code. handleSync tells you the entry point. It does not tell you whether it validates, transforms, persists, or retries. Name the operation, not the trigger.

Exception — UI event handlers: in component files (e.g., React .tsx), handle* is the established convention for DOM event callbacks (handleSubmit, handleChange, handleClose). These are scoped to the component and the "event being handled" is self-evident from the UI context. The anti-pattern label applies to backend / service / utility functions where the operation ambiguity is real.

Variable naming — noun-first:

2. Polysemy Resolution (Disambiguation)

Polysemy is when one word carries multiple meanings. In natural language, surrounding context resolves the ambiguity automatically. In code and documentation, context is often missing — and the resolution cost falls on every reader.

Polysemy Map (Examples)

These words are commonly polysemous in software. The unqualified form should not appear in typed code; always use the qualified form.

Resolution Protocol

When you encounter an ambiguous term:

1. Identify all contexts where the term appears in the codebase. Grep before assuming.
2. Choose the qualified form for each code context. The project glossary is the authority on canonical forms.
3. Update the variable name, column name, or UI label to use the qualified form.
4. Document the disambiguation in a code comment if the qualified form is not yet self-evident.

Code naming rule: the qualified form goes into the identifier. No fallback to context inference.

// Wrong — "shipping" is ambiguous
const shipping = order.shipping_cost + order.shipping_charged;

// Right — each concept is named precisely
const shippingCostCents = order.shipping_cost_cents;       // seller pays this
const shippingChargedCents = order.shipping_charged_cents; // customer pays this

Documentation rule: the first occurrence of an ambiguous term in any doc must be qualified. Subsequent occurrences may use the short form only if the surrounding context is unambiguous.

3. Tone and Register

Register is the level of formality and technicality appropriate for a given audience and context. The same fact requires different register for an end-user, an agent, and a developer. Writing in the wrong register is a communication failure even when the content is accurate.

Register Map

End-User Register: Detailed Rules

The end-user register has the tightest constraints because it directly affects user trust and conversion.

Vocabulary:

• Use domain terms the user already knows: revenue, margin, SKU, fulfillment for an e-commerce audience; subscriber, MRR, churn for a SaaS audience.
• Avoid internal technical terms: canonical, reconciliation (say "matched" instead), backfill (say "importing past data").
• Use "you" and "your" — the UI speaks to the user directly.
• Quantify time when you know it: "~2 minutes" beats "just a moment".

Sentence structure:

• Lead with the outcome, not the process. "See your real profit per order" not "This feature connects your order data and calculates profit."
• Use active voice. "Sync paused" not "Sync has been paused."
• One idea per sentence in error messages.

Tone:

• Calm authority, not startup hype. "Know your real profit." not "Unlock powerful profit insights!"
• Honest about missing data. "Connecting your fulfillment partner will reveal your production cost." not "Your profit: $0.00" when production cost is unknown.
• Never blame the user. "We couldn't connect" not "You entered the wrong API key."

Agent-Facing Register: Detailed Rules

Agent-facing docs prioritize density and parsability over warmth.

Structure:

• Tables over prose for any comparison of 3+ items.
• Bullet points for sequential rules or lists of 3+ items.
• Code blocks for any naming example, pattern, or anti-pattern.
• No narrative introductions — lead with the rule.

Vocabulary:

• Use precise technical terms without definition: polysemy, morpheme, compound, register. The agent has loaded the skill.
• Name file paths absolutely (e.g., src/lib/payment/processor.ts), not "the payment processor".
• Reference the evidence: "Verified in cardComponent.tsx line 42" not "this is the pattern used".

Developer-Facing Register: Detailed Rules

Developer-facing content (code comments, ADRs, PR descriptions) lives closer to the code and prioritizes rationale.

Code comments:

• Explain why, not what. The code is the what. // must use the tenant-scoped query — raw query() leaks across tenants (ABC-123) not // using tenant-scoped query here.
• Flag non-obvious decisions: // COALESCE prevents null overwrite on re-webhook — partner has a 30-day deletion window.
• Link to the issue: (ABC-123) in comments that address a known bug or decision.

PR descriptions:

• Problem statement first: what was broken or missing.
• Solution: what changed and why this approach.
• Test protocol: how to verify the change is correct.
• Breaking changes: explicit callout if any contract changed.

4. Cross-Cultural Linguistic Awareness

Implementation details for currency formatting, date locale rules, and number systems belong to a separate i18n skill. This section covers only the linguistic awareness that shapes those decisions: different languages have fundamentally different number structures, grammatical gender, and script directions.

Key linguistic facts that affect i18n decisions:

• Number structure differs by language. English uses comma-grouping and period-decimal (1,234.56); many European locales reverse them (1.234,56). This is not a formatting preference — it changes how numbers are read. A developer writing number logic must know the linguistic reason for the locale parameter, not just its mechanical effect.
• Currency symbols carry meaning beyond their value. $ signals USD to a US reader; € signals EUR. Bare numbers without currency symbols are linguistically incomplete — they transfer a quantity but not a unit. Always qualify with the currency code or symbol.
• Grammatical gender affects pluralization. English has no grammatical gender for numbers, but many languages do. A string like "1 order" vs "2 orders" is a morphological change; other languages require agreement with grammatical gender of the noun. Hardcoded plurals are always wrong.
• Script direction is architectural. Arabic, Hebrew, and Persian run right-to-left. This is not a CSS toggle — it reverses spatial reasoning (icons, progress bars, layout flow). Affects component architecture far upstream of any formatting call.
• Operator-language vs audience-language axis. When the maintainer's primary language differs from the target audience's, code identifiers and UI copy should follow the audience's language conventions, never the maintainer's. Personal notes can stay in the operator's language; anything an agent or another developer reads must be in the project's chosen lingua franca.

Operator-Language Code Mixing

When the maintainer is bilingual, all code-facing surfaces must be in the project's chosen language:

Anti-pattern: business concepts from the operator's native language slipping into code as abbreviations. If a word in the operator's language collides with a different meaning in the project language, the abbreviation is unsafe even when the operator finds it natural.

5. Error-Message Linguistics

Error messages are the most linguistically precise text in any software product. They arrive at the worst moment for the reader (something went wrong) and must deliver maximum information in minimum words.

The Three-Part Structure

Every error message must answer three questions in order:

1. What happened? — Name the failure specifically. Not "an error occurred."
2. Why? — Name the cause if known. Skip this if the cause is unknown — do not guess.
3. What to do next? — Give one specific action. Not "contact support" as a first resort.

Blame-Free Language

Rule: never use "you" in a negative construction. "You haven't…", "You entered…", "Your connection failed…" all assign blame. Reframe to a system state or a missing action.

Specificity Rules

Include the entity name when the error involves a specific record, connection, or resource. order #1247 beats "an order"; your store "my-shop" beats "your store".

Actionability

Every error that requires user action must end with a specific next step:

Never end with a bare error. If the error is purely informational (system log, agent message), mark it explicitly as informational so the reader knows no action is needed.

6. Anti-Patterns

Verification

Before committing code, writing documentation, or shipping UI copy, run through this checklist.

Naming (Code)

LINGUISTICS NAMING CHECK
========================
[ ] Every function is verb-first with a specific subject (not handle/do/process/get alone in non-UI code)
[ ] Every variable is noun-first with qualifiers for counts, booleans, and financial values
[ ] No unqualified polysemous terms in typed code: provider, shipping, cost, margin, sync, channel, source, status
[ ] Financial values end in Cents (or specify currency in the name) and are stored as integers
[ ] Abbreviations are universally understood or defined in the project glossary
[ ] File names describe what the file does, not which workflow it belongs to
[ ] No utils.ts, helpers.ts, misc.ts — name by domain

Language (UI Copy and Error Messages)

LINGUISTICS COPY CHECK
======================
[ ] Error messages follow What → Why → What to do structure
[ ] No blame-assigning language ("you entered", "you haven't", "your error")
[ ] Specific entity names included when a specific record/connection is involved
[ ] Every error that requires action has a specific next step
[ ] Register matches the audience (end-user: warm + plain; agent: dense + precise; developer: rationale-focused)
[ ] No agent-register terms in end-user copy (canonical, reconciliation, backfill, orchestration)
[ ] Financial terms match the project glossary definitions

Internationalization

LINGUISTICS I18N CHECK
======================
[ ] All code identifiers are in the project's chosen language
[ ] No business concepts from the operator's native language slipping into code abbreviations
[ ] UI copy targets the audience's language and conventions, not the operator's
[ ] Null financial values display as — or "unknown", never as $0.00 (null ≠ zero)
[ ] Currency symbol or code is always present — bare numbers without units are linguistically incomplete
[ ] Implementation details (Intl.NumberFormat, date locale, plural handling) are deferred to project i18n tooling or platform docs

Do NOT Use When

Key Sources

Public Grounding Checked 2026-05-19

• Google Developer Documentation Style Guide: Active voice, Voice and tone, and Write for a global audience. Grounds active/passive actor clarity, conversational but direct developer register, short unambiguous sentences, terminology consistency, and global-audience translation constraints.
• Microsoft Learn: Writing style for Windows apps and Error Message Guidelines. Grounds non-blaming error messages, clear next steps, active voice where useful, present-tense state descriptions, and avoiding generic one-size-fits-all errors.
• W3C WCAG 2.2: Input Assistance and related Understandable criteria. Grounds the requirement that detected input errors be identified and described in text, that labels/instructions exist when input is required, and that known correction suggestions be provided when safe.
• Nielsen Norman Group: 10 Usability Heuristics and Hostile Patterns in Error Messages. Grounds user-language matching, consistency of words/actions, plain-language error recovery, avoiding premature error scolding, and reserving disruptive error styling for real errors.

Classical and Book Grounding

• Saussure, F. de (1916). Cours de linguistique générale / Course in General Linguistics. Payot. Signifier/signified distinction and meaning by contrast; supports treating identifiers as meaning-bearing contracts.
• Lyons, J. (1977). Semantics (2 vols.). Cambridge University Press. Structural semantics, polysemy, synonymy, hyponymy, and systematic analysis of word meaning.
• Cruse, D. A. (1986). Lexical Semantics. Cambridge University Press. Word-level meaning relationships and polysemy resolution by qualification.
• Halliday, M. A. K., & Matthiessen, C. M. I. M. (2014). An Introduction to Functional Grammar (4th ed.). Routledge. Systemic-functional grammar and register through field, tenor, and mode.
• Grice, H. P. (1975). "Logic and Conversation." In Syntax and Semantics, Vol. 3: Speech Acts. Academic Press. Cooperative principle and maxims of quantity, quality, relation, and manner.
• Searle, J. R. (1969). Speech Acts: An Essay in the Philosophy of Language. Cambridge University Press. Speech-act theory for distinguishing reporting, instructing, and accusing.
• Austin, J. L. (1962). How to Do Things with Words. Oxford University Press. Performative utterances and locutionary/illocutionary/perlocutionary acts.
• Williams, J. M., & Bizup, J. (2017). Style: Lessons in Clarity and Grace (12th ed.). Pearson. Cognitive-linguistic clarity principles for technical and public prose.