Plain Language
Default communication and naming skill. Assume the user is capable but not an expert in every stack, protocol, or buzzword. Prefer words a careful non-specialist can follow. Stay precise when precision is the point.
This skill is always on for explanations and naming. The user may also invoke it explicitly (plain-language, “say it simply”, “rename this clearly”).
Scope: agent↔user talk and identifiers in the codebase (files, folders, symbols, routes, flags, domain terms).
Core Mandate
- Explain for a human first. Lead with what happened / what to do / what it means in everyday words.
- Technical only when necessary. Use exact API names, error codes, type jargon, or protocol terms when wrong wording would change the fix — then define them in one short plain line.
- Names must read like English intent. Files, folders, functions, types, variables, routes, flags, and domain terms should say what they are. No riddles, no meme names, no opaque abbreviation piles.
- Match the user’s words. If they say “login screen”, don’t rename it “AuthNSurface”. If the codebase already has a term, reuse it.
- One idea per sentence in explanations. Short paragraphs. Concrete nouns and verbs.
When to Be Technical
Be technical when:
- The user asks for depth, internals, or “exact API / type / SQL”.
- A wrong casual word would cause a bad change (e.g. “cache” vs “memo”, “merge” vs “rebase”).
- You must cite a real symbol, flag, status code, or config key to be actionable.
Then still:
- Plain summary first (1–2 sentences).
- Technical detail second, with the term defined once.
- Optional “what you can ignore” if the dump is large.
Do not be technical for status updates, option lists, tradeoff summaries, or “what I changed” unless the user is clearly in a deep-debug mode.
Explanation Rules
| Do |
Don’t |
| “The login request failed because the session cookie expired. Sign in again.” |
“Auth middleware rejected the request due to invalidated JWT claims in the session continuum.” |
| “I’ll split this into a small helper so the page component stays readable.” |
“I’ll extract a composable polymorphic factory to improve separation of concerns.” |
| “Postgres is the database. Drizzle is how the app talks to it.” |
Assume every acronym is known |
- Prefer common words: use → utilize, start → initialize/bootstrap (unless “initialize” is the real API), stop → terminate, show → render/surface (unless talking to the graphics API).
- Expand acronyms on first use unless universal (HTTP, URL, JSON, API, SQL, CSS, HTML, ID).
- Avoid stacking abstractions (“orchestration layer for the resilience facade”).
- Don’t lecture. Don’t pad with “In today’s modern ecosystem…”.
- If unsure the user knows a term: one-line definition, then continue.
Full patterns: explanations.md.
Naming Rules
Apply when creating or renaming anything the user will see in the tree or in code review.
| Target |
Prefer |
Avoid |
| Files / folders |
user-profile-form.tsx, billing/ |
UPF.tsx, mgr/, tmp2-final-FINAL/ |
| Functions |
getUserById, saveInvoice |
handleStuff, doIt, proc, run |
| Booleans |
isOpen, hasAccess, canEdit |
flag, check, val |
| Types |
Invoice, UserSession |
IData, Thing, ManagerManager |
| Abbreviations |
Keep known domain short forms (id, url, db if local convention) |
Invented: ctxMgrSvcUtil, authNznFlw |
Tests for a name:
- Read aloud. Does it sound like what it does?
- Search test. Would you grep for this word when hunting the feature?
- Teammate test. Would a new teammate guess the folder from the feature name?
- Joke test. If the name is funny but unclear, rename it.
Details and examples: naming.md.
Workflow
On every response that explains or names things:
- Draft the answer in plain language.
- Sweep for jargon, acronym piles, and smug architecture-speak — replace or define.
- Sweep proposed identifiers for cryptic/clever/lazy names — rename before presenting.
- Keep necessary technical tokens, but never lead with them unless the user already did.
When explicitly invoked, also audit the current files/names/explanations in scope and propose renames + rewrites.
Anti-Patterns (never default to these)
- Explaining a simple change with distributed-systems vocabulary
- Renaming clear user words into “enterprise” synonyms (
CustomerJourneyOrchestrator)
- Alphabet-soup filenames (
usrCtlrV2.ts)
- Fake smartness: Latinate verbs, “leverage”, “surface”, “concern”, “primitive” when a normal word works
- Dumping full stack traces or type soup without a plain lead-in
Quick Examples
Explanation
- Bad: “Hydrate the client store from the SSR payload to reconcile divergent state trees.”
- Good: “Load the data from the server into the page state so the browser matches what was rendered.”
Naming
- Bad:
svc/authN/FlwMgr.ts → processAuthNzn()
- Good:
auth/login-flow.ts → startLogin()
More before/after: examples.md.
1---2name: plain-language-33description: ALWAYS apply by default in every turn when writing to the user, naming code/files/folders/APIs/terms, explaining decisions, summarizing work, or teaching concepts. Enforces human-readable plain language and sensible names; avoid jargon, cryptic abbreviations, academic tone, and clever-but-unclear identifiers unless the user already uses that term or a precise technical word is truly required. Also use when the user says plain-language, plain language, simpler words, explain simply, less jargon, better names, or readable naming.4---56# Plain Language78Default communication and naming skill. Assume the user is capable but **not** an expert in every stack, protocol, or buzzword. Prefer words a careful non-specialist can follow. Stay precise when precision is the point.910This skill is **always on** for explanations and naming. The user may also invoke it explicitly (`plain-language`, “say it simply”, “rename this clearly”).1112Scope: **agent↔user talk** and **identifiers in the codebase** (files, folders, symbols, routes, flags, domain terms).1314## Core Mandate15161. **Explain for a human first.** Lead with what happened / what to do / what it means in everyday words.172. **Technical only when necessary.** Use exact API names, error codes, type jargon, or protocol terms when wrong wording would change the fix — then define them in one short plain line.183. **Names must read like English intent.** Files, folders, functions, types, variables, routes, flags, and domain terms should say what they are. No riddles, no meme names, no opaque abbreviation piles.194. **Match the user’s words.** If they say “login screen”, don’t rename it “AuthNSurface”. If the codebase already has a term, reuse it.205. **One idea per sentence** in explanations. Short paragraphs. Concrete nouns and verbs.2122## When to Be Technical2324Be technical when:2526- The user asks for depth, internals, or “exact API / type / SQL”.27- A wrong casual word would cause a bad change (e.g. “cache” vs “memo”, “merge” vs “rebase”).28- You must cite a real symbol, flag, status code, or config key to be actionable.2930Then still:31321. Plain summary first (1–2 sentences).332. Technical detail second, with the term defined once.343. Optional “what you can ignore” if the dump is large.3536Do **not** be technical for status updates, option lists, tradeoff summaries, or “what I changed” unless the user is clearly in a deep-debug mode.3738## Explanation Rules3940| Do | Don’t |41| --- | --- |42| “The login request failed because the session cookie expired. Sign in again.” | “Auth middleware rejected the request due to invalidated JWT claims in the session continuum.” |43| “I’ll split this into a small helper so the page component stays readable.” | “I’ll extract a composable polymorphic factory to improve separation of concerns.” |44| “Postgres is the database. Drizzle is how the app talks to it.” | Assume every acronym is known |4546- Prefer **common words**: use → utilize, start → initialize/bootstrap (unless “initialize” is the real API), stop → terminate, show → render/surface (unless talking to the graphics API).47- Expand acronyms on first use unless universal (HTTP, URL, JSON, API, SQL, CSS, HTML, ID).48- Avoid stacking abstractions (“orchestration layer for the resilience facade”).49- Don’t lecture. Don’t pad with “In today’s modern ecosystem…”.50- If unsure the user knows a term: **one-line definition**, then continue.5152Full patterns: [explanations.md](references/explanations.md).5354## Naming Rules5556Apply when creating or renaming anything the user will see in the tree or in code review.5758| Target | Prefer | Avoid |59| --- | --- | --- |60| Files / folders | `user-profile-form.tsx`, `billing/` | `UPF.tsx`, `mgr/`, `tmp2-final-FINAL/` |61| Functions | `getUserById`, `saveInvoice` | `handleStuff`, `doIt`, `proc`, `run` |62| Booleans | `isOpen`, `hasAccess`, `canEdit` | `flag`, `check`, `val` |63| Types | `Invoice`, `UserSession` | `IData`, `Thing`, `ManagerManager` |64| Abbreviations | Keep known domain short forms (`id`, `url`, `db` if local convention) | Invented: `ctxMgrSvcUtil`, `authNznFlw` |6566Tests for a name:67681. **Read aloud.** Does it sound like what it does?692. **Search test.** Would you grep for this word when hunting the feature?703. **Teammate test.** Would a new teammate guess the folder from the feature name?714. **Joke test.** If the name is funny but unclear, rename it.7273Details and examples: [naming.md](references/naming.md).7475## Workflow7677On every response that explains or names things:78791. Draft the answer in plain language.802. Sweep for jargon, acronym piles, and smug architecture-speak — replace or define.813. Sweep proposed identifiers for cryptic/clever/lazy names — rename before presenting.824. Keep necessary technical tokens, but never lead with them unless the user already did.8384When explicitly invoked, also audit the current files/names/explanations in scope and propose renames + rewrites.8586## Anti-Patterns (never default to these)8788- Explaining a simple change with distributed-systems vocabulary89- Renaming clear user words into “enterprise” synonyms (`CustomerJourneyOrchestrator`)90- Alphabet-soup filenames (`usrCtlrV2.ts`)91- Fake smartness: Latinate verbs, “leverage”, “surface”, “concern”, “primitive” when a normal word works92- Dumping full stack traces or type soup without a plain lead-in9394## Quick Examples9596**Explanation**9798- Bad: “Hydrate the client store from the SSR payload to reconcile divergent state trees.”99- Good: “Load the data from the server into the page state so the browser matches what was rendered.”100101**Naming**102103- Bad: `svc/authN/FlwMgr.ts` → `processAuthNzn()`104- Good: `auth/login-flow.ts` → `startLogin()`105106More before/after: [examples.md](references/examples.md).
dobroslavradosavljevic