@skill-graph/cli 0.5.6

package/marketplace/skills/linguistics/SKILL.md

@@ -0,0 +1,429 @@
+---
+name: linguistics
+description: "Use when choosing names for files/functions/variables/types/columns, writing or reviewing UI copy/error/onboarding text, disambiguating overloaded terms, or matching tone to end-user/agent/developer audiences. Covers morphology, compound-word order, abbreviation policy, verb-noun rules, polysemy resolution, audience register, blame-free error-message structure, and cross-cultural product-copy awareness. Do NOT use for casing conventions (use naming-conventions), doc structure/type selection (use documentation), or call-site-wide renames (use refactor)."
+license: MIT
+compatibility: "Provider-/runtime-/stack-agnostic. The morphology, polysemy, register, and error-message rules apply to any software product written in any human-spoken language; the casing-convention table is illustrative for typical OSS stacks (TypeScript, SQL, CSS, Python) — substitute the conventions of your own stack."
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.1.0\",\"type\":\"capability\",\"category\":\"foundations\",\"domain\":\"foundations/language\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"polysemy resolution\\\\\\\",\\\\\\\"polysemy map\\\\\\\",\\\\\\\"register selection\\\\\\\",\\\\\\\"audience register\\\\\\\",\\\\\\\"blame-free error wording\\\\\\\",\\\\\\\"three-part error structure\\\\\\\",\\\\\\\"morphology rules\\\\\\\",\\\\\\\"compound-word ordering\\\\\\\",\\\\\\\"abbreviation policy\\\\\\\",\\\\\\\"ambiguous identifier qualification\\\\\\\",\\\\\\\"linguistic precision\\\\\\\",\\\\\\\"register mismatch\\\\\\\",\\\\\\\"unqualified polysemous identifier\\\\\\\",\\\\\\\"error-message linguistics\\\\\\\",\\\\\\\"cross-cultural linguistic awareness\\\\\\\",\\\\\\\"verb-noun naming rule\\\\\\\",\\\\\\\"what-why-action error structure\\\\\\\"]\",\"examples\":\"[\\\\\\\"this variable is named provider but it could mean fulfillment, auth, or payment — what linguistic rule applies?\\\\\\\",\\\\\\\"rewrite this error message to be specific, blame-free, and actionable\\\\\\\",\\\\\\\"the word shipping means seller cost in one file and customer charge in another — how do we resolve the polysemy without a glossary cleanup?\\\\\\\",\\\\\\\"should this helper file be called utils.ts, helpers.ts, or something domain-specific?\\\\\\\",\\\\\\\"explain how to phrase the same finance concept for an end-user, an agent, and a developer\\\\\\\",\\\\\\\"audit this UI copy for register mismatch with the end-user audience\\\\\\\",\\\\\\\"when is an abbreviation acceptable in a code identifier?\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"decide kebab-case vs snake_case vs camelCase for new database columns\\\\\\\",\\\\\\\"restructure this doc into a tutorial format with progressive disclosure\\\\\\\",\\\\\\\"implement Intl.NumberFormat for DKK vs USD currency formatting\\\\\\\",\\\\\\\"give me the canonical definition of reconciliation in our domain\\\\\\\",\\\\\\\"review this PR for code quality and missing tests\\\\\\\",\\\\\\\"rename this function and update every call-site across the repo\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"naming-conventions\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"naming-conventions owns the deterministic casing/format choice per artifact kind (kebab-case for files, camelCase for TS, snake_case for SQL); linguistics owns the linguistic rationale (morphology, polysemy resolution, register fit, blame-free copy) — the same 'help me name this' prompt routes by whether the user wants the convention itself or the linguistic basis behind it\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"refactor\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"refactor owns behavior-preserving structural change including rename mechanics across call sites; linguistics owns the linguistic decision of what the new name should be — the same 'rename this thing' prompt routes by whether the trigger is the rename mechanics or the naming choice itself\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"prompt-craft\\\\\\\",\\\\\\\"intent-recognition\\\\\\\",\\\\\\\"code-review\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"naming-conventions\\\\\\\",\\\\\\\"code-review\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":365,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"Linguistics in software is to identifier names what civil engineering is to bridge geometry — the bridge holds up because the geometry obeys load-bearing rules, not because the bridge is artful; the rules don't make the bridge beautiful, but ignoring them makes the bridge fall down. A name like `handleContinue` is the equivalent of a beam sized by intuition: it might hold, but you've forfeited the proof that it will.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Linguistics applied to software is the discipline of using the rules of human language — morphology, semantics, pragmatics, sociolinguistics — to shape the words inside a software system: identifier names, type labels, error messages, UI copy, and documentation prose. Drawing from Saussure's signifier/signified distinction, Lyons's structural semantics, and Halliday's systemic-functional grammar, it treats every name and every visible string as a small linguistic artefact whose form determines whether the reader can decode the intended meaning quickly and reliably.\\\\\\\",\\\\\\\"mental_model\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"purpose\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"boundary\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"taxonomy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"analogy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"misconception\\\\\\\":\\\\\\\"|\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/linguistics/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/linguistics/SKILL.md
+---
+
+# Linguistics
+
+## 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 the canonical term definition, not the i18n implementation.
+
+## Philosophy
+
+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.
+
+---
+
+## 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
+
+| Convention | Typical Use | Linguistic Reason |
+|------------|-------------|-------------------|
+| `camelCase` | Variables, function names in many languages | Each morpheme boundary is marked by capitalization; reads as one compound word |
+| `PascalCase` | Types, classes, components | Same compound logic, but signals "noun/thing" rather than "action/value" |
+| `kebab-case` | File names, CSS classes, URL paths | Human-readable in filesystem and URL contexts where case is often flattened |
+| `snake_case` | Database columns, Python identifiers | Separator makes each morpheme explicit; SQL is case-insensitive so underscores are the only safe delimiter |
+| `SCREAMING_SNAKE` | Constants, enums, environment variables | All-caps signals immutability; snake separators keep it readable |
+
+**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.
+
+| Compound | Head | Modifier | Reads as |
+|----------|------|----------|----------|
+| `shippingCost` | cost | shipping | "a cost, specifically for shipping" |
+| `orderCount` | count | order | "a count, specifically of orders" |
+| `fulfillmentProvider` | provider | fulfillment | "a provider, specifically for fulfillment" |
+
+**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:
+
+| Ambiguous | Qualified | Domain |
+|-----------|-----------|--------|
+| `shipping` | `shippingCostCents` | Outbound cost paid by the seller |
+| `shipping` | `shippingChargedCents` | Amount charged to the customer |
+| `provider` | `fulfillmentProvider` | Fulfillment partner |
+| `provider` | `authProvider` | Authentication identity provider |
+| `provider` | `paymentProvider` | Payment processor |
+| `cost` | `productionCostCents` | Production / fulfillment cost |
+| `cost` | `subscriptionCost` | Plan pricing |
+| `cost` | `tokenCostUsd` | Inference / API cost |
+
+**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:**
+
+| Verb | When to use | Example |
+|------|-------------|---------|
+| `get` | Retrieval from a source, may be async | `getOrders`, `getOrderById` |
+| `fetch` | Specifically async network call | `fetchExternalOrders` |
+| `load` | Load into memory/state from a slower source | `loadDashboardData` |
+| `validate` | Check correctness, return boolean or throw | `validateWebhookPayload` |
+| `parse` | Convert raw input into typed output | `parseConnectionString` |
+| `transform` | Convert one structured form to another | `transformPaymentEvent` |
+| `convert` | Change units or formats, same semantic content | `convertCentsToDisplayAmount` |
+| `calculate` | Derive a computed value | `calculateNetMargin` |
+| `create` | Instantiate and persist | `createPlatformConnection` |
+| `update` | Modify existing entity | `updateOrderStatus` |
+| `delete` / `remove` | Destructive operations | `deleteAccount`, `removeLineItem` |
+| `handle` | Entry point for events/webhooks (and nothing else) | `handleIncomingWebhook` |
+| `process` | Multi-step pipeline execution | `processVerifiedWebhook` |
+| `extract` | Pull a subset from a larger structure | `extractOrderPii` |
+| `format` | Produce a display string | `formatCurrencyDisplay` |
+| `build` | Assemble a complex object | `buildCanonicalOrder` |
+
+**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:**
+
+| Pattern | Example | Why |
+|---------|---------|-----|
+| Boolean: `is` + adjective | `isValid`, `isActive`, `isReconciled` | Reads as a question in conditions: `if (isValid)` |
+| Boolean: `has` + noun | `hasConnection`, `hasFinancialData` | "Does X have Y?" — confirms presence |
+| Boolean: `can` + verb | `canExportOrders`, `canEditPricing` | Permission check — "is X allowed to do Y?" |
+| Count: noun + `Count` | `orderCount`, `lineItemCount` | Disambiguates from the collection |
+| Collection: plural noun | `orders`, `lineItems`, `errors` | Plural form signals collection; no `List`, `Array`, `Set` suffix |
+| Nullability | Express via the type system, not the name | Use `T | null`, not `*OrNull` suffixes |
+| Currency-as-integer | noun + `Cents` (or unit suffix) | Mandatory for any financial integer; never store money as a float |
+
+---
+
+## 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.
+
+| Ambiguous term | Context A | Context B | Context C | Qualified forms |
+|----------------|-----------|-----------|-----------|-----------------|
+| **margin** | Finance: profit as % of revenue | CSS: spacing property | Domain-typical range (industry-specific) | `marginPercent` (finance), CSS property (leave as-is in stylesheet) |
+| **shipping** | Cost paid by the seller to a carrier | Amount charged to the customer on invoice | The carrier itself | `shippingCostCents`, `shippingChargedCents`, `carrierName` |
+| **provider** | Fulfillment partner | Authentication identity provider | Payment processor | `fulfillmentProvider`, `authProvider`, `paymentProvider` |
+| **cost** | Production / fulfillment cost | Subscription plan pricing | Inference / API token spend | `productionCostCents`, `subscriptionPriceCents`, `tokenCostUsd` |
+| **sync** | Data import from an external platform | URL ↔ UI state coordination | Inter-process / inter-agent coordination | `platformSync`, `stateSync`, `agentSync` |
+| **channel** | Sales platform | Alert delivery medium | Chat-platform channel | `salesChannel`, `alertChannel`, `chatChannel` |
+| **source** | Data origin (which platform) | Source code file | Content source | `dataSource`, `sourceFile`, `contentSource` |
+| **status** | Order status (pending / shipped) | Fulfillment status (in production) | Task status (in progress / done) | `orderStatus`, `fulfillmentStatus`, `taskStatus` |
+| **connection** | Platform integration (a third-party connected) | Database connection pool | WebSocket connection | `platformConnection`, `dbConnection`, `wsConnection` |
+| **confidence** | Data completeness score (0–100) | Statistical probability | Colloquial certainty | `dataConfidenceScore`, keep `confidence` in statistical contexts |
+
+### 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.
+
+```typescript
+// 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
+
+| Audience | Context | Register | Character | Example |
+|----------|---------|----------|-----------|---------|
+| **End-user** | UI copy, tooltips, empty states, error messages | Warm, plain, action-oriented | A knowledgeable friend who respects the user's time and intelligence | "Connect your fulfillment partner to see your real production cost per order." |
+| **End-user** | Onboarding | Confident, step-by-step, time-honest | A setup guide written by someone who has done this a hundred times | "Step 2 of 5: Link your storefront. Takes about 2 minutes." |
+| **Agent** | Skill / capability files | Dense, precise, reference-heavy | A technical spec from a colleague who assumes domain knowledge | "Use `fulfillmentProvider`, never unqualified `provider`. Three distinct meanings exist." |
+| **Agent** | Structured logs | Diagnostic, no hedging | A structured log entry | `[WEBHOOK_FAILED] order_id=12345 reason=hmac_mismatch retry=true` |
+| **Developer** | Code comments | Concise, rationale-focused, explains *why* | A note from the author who knows the reader is technical | `// Using the org-scoped query — must stay tenant-scoped (ABC-123)` |
+| **Developer** | Architecture decision records | Formal, decision-focused, versioned | An architectural decision record | "Decision: use COALESCE(EXCLUDED.col, existing.col) to prevent null overwrites on upsert." |
+| **Developer** | PR descriptions | Technical, factual, testable | A clear brief for a code reviewer | "Adds HMAC verification to platform webhooks. Test: curl the endpoint without the signature header — expect 401." |
+
+### 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:
+
+| Domain | Rule | Reason |
+|--------|------|--------|
+| Code identifiers | Project language only | Global readability; future contributors may not read the operator's native language |
+| UI copy | Audience language only | The product speaks the audience's language |
+| Internal docs (skill files, ADRs) | Project language only | Agent-readable docs must be in a single language |
+| Commit messages | Project language only | Conventional-commit type/scope terms are typically English |
+| Code comments | Project language only | Agents and developers across regions read these |
+| Personal notes (private) | Operator's native language acceptable | Private communication between operator and operator-only tools |
+| Business term references | Qualify if a non-project-language term is used | Proper nouns (carrier names, regulatory terms) are acceptable as borrowed words |
+
+**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.
+
+| Pattern | Example |
+|---------|---------|
+| What → Why → What to do | "Order sync paused — your API key expired. Open Settings → Integrations to reconnect." |
+| What → What to do (cause unknown) | "Couldn't load your orders. Try refreshing. If this continues, check your storefront connection." |
+| What (system message, no user action) | "Webhook received but could not be verified. The payload was rejected." |
+
+### Blame-Free Language
+
+| Blame-assigning (wrong) | Blame-free (right) | Why |
+|------------------------|---------------------|-----|
+| "You entered the wrong API key." | "We couldn't verify your API key." | Passive construction removes blame; "verify" names the operation |
+| "Invalid input." | "This field requires a number between 1 and 100." | Describe what's needed, not what was wrong |
+| "You haven't connected the fulfillment partner yet." | "Connect your fulfillment partner to see your production cost." | Positive framing — lead with the outcome |
+| "Your sync failed." | "Sync paused — we'll retry automatically in 5 minutes." | "Your sync failing" reads as the user's fault; "sync paused" is a system state |
+
+**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
+
+| Too vague | Specific | Why |
+|-----------|----------|-----|
+| "Something went wrong." | "Order sync failed — the API returned a 429 (rate limit). Retrying in 60 seconds." | Names the operation, the error code, and the recovery |
+| "Error loading data." | "Couldn't load orders for the last 30 days. Your storefront connection may have expired." | Names the data type, time range, and probable cause |
+| "Action failed." | "Couldn't archive order #1247 — it's currently in fulfillment." | Names the order, the operation, and the blocking state |
+
+**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:
+
+| Error type | Actionable ending |
+|------------|-------------------|
+| Connection expired | "Open Settings → Integrations to reconnect." |
+| Missing source data | "Connect your fulfillment partner to see your production cost." |
+| Sync paused | "We'll retry in 5 minutes. Or reconnect now in Settings → Integrations." |
+| Rate limit hit | "We're retrying automatically. No action needed." |
+| Unknown error | "Refresh the page, or check your connection in Settings." |
+
+**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
+
+| Anti-pattern | Example | Why it fails | Correct pattern |
+|-------------|---------|--------------|-----------------|
+| **Generic verb names** | `handleContinue()`, `handleRefresh()`, `handleExport()` in non-UI code | Carries too little semantic load once you leave the local UI context | Name the operation and its subject: `transformPaymentEvent()`, `validateWebhookPayload()` |
+| **Unqualified polysemous terms** | `provider`, `shipping`, `cost`, `margin` in typed code | Ambiguous — requires context to resolve | Always compound with domain: `fulfillmentProvider`, `shippingCostCents`, `productionCostCents`, `marginPercent` |
+| **Register mismatch** | "COGS null — display `—`" in an end-user tooltip | Agent register in an end-user context | "Cost data not yet available for this order." |
+| **Blame-assigning errors** | "You haven't connected your storefront yet." | Assigns blame; creates friction | "Connect your storefront to start tracking revenue." |
+| **Abbreviation overload** | `calcMgrSvcUtil()` | Three unrecognized abbreviations; zero parsability | `calculateManagedServiceUtilization()` (or rename the concept) |
+| **False precision in i18n** | `$${(cents / 100).toFixed(2)}` | Hardcoded USD symbol, no locale, bypasses any shared formatter | Use the project's currency formatter or `Intl.NumberFormat(...)` |
+| **Vague error messages** | "Error 500. Please try again." | Names neither the operation nor the cause | "Sync failed. We'll retry automatically — check Settings if this persists." |
+| **Implicit null = zero** | Display `$0.00` when the cost field is null | Null means *unknown*; zero means *confirmed zero*. `$0.00` cost implies 100% margin | Display `—` or "Cost unknown" when null |
+| **Utility file names** | `utils.ts`, `helpers.ts`, `misc.ts` | Non-names that aggregate unrelated functionality | Name by domain: `orderCalculations.ts`, `webhookValidation.ts`, `currencyFormatting.ts` |
+
+---
+
+## Verification
+
+Before committing code, writing documentation, or shipping UI copy, run through this checklist.
+
+### Naming (Code)
+
+```text
+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)
+
+```text
+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
+
+```text
+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 the i18n skill
+```
+
+---
+
+## Do NOT Use When
+
+| Instead, use | Why |
+|---|---|
+| `naming-conventions` | Deciding the casing format for an artifact kind (kebab vs camel vs snake). naming-conventions owns the convention; linguistics owns the linguistic basis (morphology, polysemy, register). |
+| `documentation` | Choosing a doc type, structuring a doc, or applying progressive disclosure. documentation owns doc architecture; linguistics owns the prose-form rules inside docs. |
+| `refactor` | Renaming a thing across many call sites or restructuring code without behavior change. refactor owns the rename mechanics; linguistics owns the linguistic decision of what the new name should be. |
+| `code-review` | Judging a specific PR or change for correctness, security, or quality. code-review uses linguistic feedback as one input; it does not own the linguistic rules. |
+| (a glossary skill) | Defining the canonical meaning of a domain term. A glossary owns the *definition*; linguistics owns the *consistent application* of definitions in names and copy. |
+| (a copywriting skill) | Drafting product messaging, marketing copy, or final user-facing CTA text. Copywriting owns the messaging; linguistics owns the structural form rules under that messaging. |
+| (an i18n skill) | Implementing locale-aware formatting (`Intl.NumberFormat`, date pickers, ICU plurals). i18n owns the implementation; linguistics owns the linguistic awareness behind it. |
+
+## Key Sources
+
+- Saussure, F. de (1916). *Cours de linguistique générale* / *Course in General Linguistics*. Payot. The foundational distinction between *signifier* and *signified*, and the principle that meaning lives in systems of contrast. The theoretical basis for treating identifier names as contracts.
+- Lyons, J. (1977). *Semantics* (2 vols.). Cambridge University Press. The canonical structural-semantics textbook; polysemy, synonymy, hyponymy, and the framework for analyzing word meaning systematically.
+- Cruse, D. A. (1986). *Lexical Semantics*. Cambridge University Press. Detailed treatment of word-level meaning relationships; the reference for understanding how polysemy works and how it can be resolved by qualification.
+- Halliday, M. A. K., & Matthiessen, C. M. I. M. (2014). *An Introduction to Functional Grammar* (4th ed.). Routledge. Systemic-functional grammar: language as meaning-making organized by *field*, *tenor*, and *mode*. The theoretical foundation for register selection by audience.
+- Grice, H. P. (1975). "Logic and Conversation." In *Syntax and Semantics, Vol. 3: Speech Acts*. Academic Press. The cooperative principle and the four maxims (quantity, quality, relation, manner); applied directly in error-message writing.
+- Searle, J. R. (1969). *Speech Acts: An Essay in the Philosophy of Language*. Cambridge University Press. Speech-act theory: what utterances *do*. Foundational for distinguishing reporting from accusing in error wording.
+- Austin, J. L. (1962). *How to Do Things with Words*. Oxford University Press. The original statement of performative utterances and locutionary/illocutionary/perlocutionary acts.
+- Williams, J. M., & Bizup, J. (2017). *Style: Lessons in Clarity and Grace* (12th ed.). Pearson. The leading modern style guide grounded in cognitive-linguistic principles; the practical descendant of structural linguistics for technical and public-facing prose.
+- Nielsen Norman Group. ["Error Message Guidelines"](https://www.nngroup.com/articles/error-message-guidelines/). Empirical UX-research statement of the what/why/what-to-do error structure and the blame-free framing rule.
+- W3C. [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/) — Understandable principle. Linguistic accessibility requirements (reading level, plain language, unambiguous error identification) at the international-standards level.

package/marketplace/skills/lint-overlay/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: lint-overlay
+description: "Use when adding or enforcing lint rules as part of a test or verification plan. Extends testing-strategy with lint-specific guidance: rule selection, gate placement, failure triage, and migration planning when introducing rules to an existing codebase. Do NOT use standalone — load the base testing-strategy skill alongside it — and do NOT use for chasing a specific lint failure in one file (that is debugging)."
+license: MIT
+compatibility: "Markdown, Git, any codebase with a lint tool"
+allowed-tools: Read Grep Bash
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"overlay\",\"category\":\"quality\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-04-18\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-13\\\\\\\",\\\\\\\"truth_source_hashes\\\\\\\":{\\\\\\\"scripts/skill-lint.js\\\\\\\":\\\\\\\"3a78f75f8921542b91dc619cd41bde29bf379de3c16bdcf3653c854ecbe9fa29\\\\\\\",\\\\\\\"scripts/lint/check-routing-quality.js\\\\\\\":\\\\\\\"b57d10f4c7c4e42a1a86c2741cbac6708e2de7dedb51b13f707283fbf91e32b5\\\\\\\",\\\\\\\"scripts/lint/check-routing-eval.js\\\\\\\":\\\\\\\"ab541922dfcbfb2cd7740c4abebb892e8b26477643e9d802fd0ea4cfbc8de649\\\\\\\",\\\\\\\"examples/evals/lint-overlay.json\\\\\\\":\\\\\\\"d60dcd4512904f36e56702d5338295dbf1238448b988dc60225fdd77285eaff9\\\\\\\",\\\\\\\"skills/testing-strategy/SKILL.md\\\\\\\":\\\\\\\"9c5da135ab8834843367da9e9120c92b57e81d1680ef84a0ea9e32f362e1456e\\\\\\\"}}\",\"eval_artifacts\":\"present\",\"eval_state\":\"passing\",\"routing_eval\":\"present\",\"stability\":\"experimental\",\"extends\":\"testing-strategy\",\"keywords\":\"[\\\\\\\"lint\\\\\\\",\\\\\\\"linting\\\\\\\",\\\\\\\"lint rules\\\\\\\",\\\\\\\"lint integration\\\\\\\",\\\\\\\"static analysis\\\\\\\",\\\\\\\"eslint\\\\\\\",\\\\\\\"format check\\\\\\\",\\\\\\\"add eslint rule\\\\\\\",\\\\\\\"lint is failing\\\\\\\",\\\\\\\"add lint check\\\\\\\",\\\\\\\"rule migration\\\\\\\",\\\\\\\"lint gate\\\\\\\",\\\\\\\"migrate legacy\\\\\\\",\\\\\\\"migrate lint\\\\\\\",\\\\\\\"phased migration\\\\\\\",\\\\\\\"phased gates\\\\\\\",\\\\\\\"legacy violations\\\\\\\",\\\\\\\"legacy lint violations\\\\\\\",\\\\\\\"noimplicitany\\\\\\\",\\\\\\\"pre-commit vs ci\\\\\\\",\\\\\\\"pre-commit gate\\\\\\\",\\\\\\\"ci gate\\\\\\\",\\\\\\\"introduce lint rule\\\\\\\",\\\\\\\"rule pre-commit\\\\\\\",\\\\\\\"rule runs pre-commit\\\\\\\"]\",\"triggers\":\"[\\\\\\\"lint-overlay\\\\\\\"]\",\"examples\":\"[\\\\\\\"plan ESLint rule introduction for a monorepo that has never had linting\\\\\\\",\\\\\\\"which lint rules should block CI and which should warn-only for now?\\\\\\\",\\\\\\\"migrate these legacy noImplicitAny violations in phased gates\\\\\\\",\\\\\\\"decide whether this new rule runs pre-commit or in CI only\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"this specific ESLint error is blocking my commit — why?\\\\\\\",\\\\\\\"decide whether to unit-test or integration-test this handler\\\\\\\",\\\\\\\"extract this repeated code pattern into a shared util\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"debugging\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"debugging fixes a specific failing lint result; lint-overlay plans rule selection and gate placement\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"refactor\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"refactor changes behavior-preserving code shape; lint-overlay is verification-plan authoring, not code modification\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"base testing-strategy owns unit-vs-integration scope selection; lint-overlay extends it only for lint-specific gate placement\\\\\\\"}]}\",\"grounding\":\"{\\\\\\\"domain_object\\\\\\\":\\\\\\\"Lint-specific verification planning in the Skill Graph starter library\\\\\\\",\\\\\\\"grounding_mode\\\\\\\":\\\\\\\"hybrid\\\\\\\",\\\\\\\"truth_sources\\\\\\\":[\\\\\\\"scripts/skill-lint.js\\\\\\\",\\\\\\\"scripts/lint/check-routing-quality.js\\\\\\\",\\\\\\\"scripts/lint/check-routing-eval.js\\\\\\\",\\\\\\\"examples/evals/lint-overlay.json\\\\\\\",\\\\\\\"skills/testing-strategy/SKILL.md\\\\\\\"],\\\\\\\"failure_modes\\\\\\\":[\\\\\\\"lint_failure_triaged_as_strategy_problem\\\\\\\",\\\\\\\"overlay_loaded_without_base_testing_strategy\\\\\\\",\\\\\\\"rule_migration_lacks_gate_placement\\\\\\\",\\\\\\\"routing_eval_claim_not_backed_by_harness\\\\\\\"],\\\\\\\"evidence_priority\\\\\\\":\\\\\\\"repo_code_first\\\\\\\"}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/lint-overlay/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/lint-overlay/SKILL.md
+---
+
+# Lint Overlay
+
+## Extends
+
+This overlay extends `testing-strategy`. Load both skills whenever lint is part of a verification plan — this overlay alone is under-specified because it relies on the base skill's effort-to-risk framework for deciding which rules to enforce at all.
+
+**What this overlay adds on top of `testing-strategy`:**
+
+| Concern | `testing-strategy` (base) | `lint-overlay` (this skill) |
+|---|---|---|
+| What to verify | Behavior under real input | Static properties of the source, independent of input |
+| When to run | At the scope dictated by risk | Before unit tests, on changed files only (unless a global rule is at risk) |
+| Failure meaning | A regression in shipped behavior | A rule violation — block the merge, do not debug it in situ |
+| Migration pattern | Write tests for existing behavior once | Introduce rules by pinning pre-change green state; fail only on new violations |
+
+**What this overlay does NOT override from the base:**
+
+- Effort-to-risk matching (base decides *whether* to lint before this decides *how*)
+- Evidence quality (lint output is evidence; the same "concrete, reproducible" rule applies)
+- Failure-case coverage (lint catches only the cases its rules know about; behavior tests still cover the rest)
+
+## Coverage
+
+- Lint as verification: when a lint step belongs in a test plan and when it is out of scope
+- Rule selection: choosing which lint rules to enforce based on the risk profile of the change
+- Lint-gate placement: where lint fits in the verification sequence relative to unit and integration tests
+- Failure triage: separating lint failures caused by the current change from pre-existing rule violations
+- Overlay discipline: what this skill adds on top of testing-strategy and what it intentionally leaves to the base
+
+## Philosophy
+
+Lint is a verification signal, not a style opinion. A lint rule exists because a pattern has a measurable cost — a bug class, a readability drop, a maintenance drag — and the rule's job is to surface that cost early enough to fix it cheaply. Rules without that grounding are style preferences dressed up as gates, and style preferences should not block merges.
+
+Three principles follow from that stance:
+
+- **Enforce only rules that were green before the change.** A new rule that fails 200 pre-existing files on its first run is not a test — it is a scope change. Pin the pre-change green state, fail only on *new* violations, and plan the cleanup as a separate migration track.
+- **Lint failures are test failures, not advisory warnings.** A rule that does not block the merge does not change behavior; it just adds noise to the log. Either the rule is worth a block or it is not a rule yet. "Warn-only" is a deployment mode for a migration window, not a permanent posture.
+- **Lint scope matches test scope.** Run lint on the files the change touches, not on the entire tree. The exception is a rule whose correctness is global (e.g., a no-circular-imports check that a local diff cannot detect) — those run tree-wide, deliberately, and their cost is acknowledged.
+
+## Overlay Rules
+
+These rules augment (not replace) the testing-strategy base skill.
+
+| Rule | When it applies | Why |
+|---|---|---|
+| Lint runs after unit tests, before integration tests | When the change touches logic and style | Lint fails are cheap to fix; catching them before integration saves context |
+| Only enforce rules that were green before the change | When introducing lint to an existing codebase | Fail on regressions, not on pre-existing violations |
+| Lint scope matches the test scope | When the diff is bounded to specific files | Run lint only on changed files unless a global rule is at risk |
+| Lint failures are blocking, not advisory | When lint is part of the official CI gate | A lint failure is a test failure; treat it the same way |
+| New lint rules require a migration plan | When adding a rule that affects many existing files | Adding a rule that immediately fails 200 files is not a test — it is a scope change |
+
+## Evals
+
+This skill ships a comprehension-eval artifact at [`examples/evals/lint-overlay.json`](https://github.com/jacob-balslev/skill-graph/blob/main/examples/evals/lint-overlay.json). Because this is an overlay, the eval prompts specifically test what the overlay adds on top of `testing-strategy` and what it deliberately leaves to the base. The eval file is how this skill is graded by `scripts/skill-audit.js --graded`.
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `testing-strategy` alone | Lint is not in scope for this change — load only the base skill |
+| `debugging` | The task is chasing a specific lint failure in one file, not planning lint-gate strategy |
+| `refactor` | The task is fixing accumulated lint debt as structural cleanup — refactor covers behavior preservation during the cleanup |