skills/unslop/SKILL.md

name	description
unslop	Cut AI tells from anything written in my projects. Apply to all prose I ship, including code comments, godoc, error strings, log lines, Svelte UI copy, docs, READMEs, and commit messages. Always apply.

Unslop

Edit text so it reads like a person who works on this codebase wrote it. This covers every writing surface in a Go/Svelte project: godoc and code comments, error and log messages, UI copy, markdown docs, commit messages, and PR descriptions.

Process

1. Scan for the patterns below.
2. Rewrite. Preserve meaning, match the surrounding voice.
3. Self-audit: "What makes this obviously AI generated?" Fix remaining tells.

Voice

• Have opinions. State what happened and what it means, don't neutrally list.
• Vary rhythm. Short sentences. Then longer ones that take their time.
• Be specific. Not "this can cause issues" but "the client stays disconnected and the request times out after 2m".
• If a sentence could appear unchanged in another project's docs, it says nothing about this one. Cut it.
• Match the existing voice. When two docs cover sibling features, they should read like the same person wrote both: same structure, same phrasing for the same concepts, same level of detail.

Go code comments

• Every commented element (func, struct, var) gets a comment whose first word is the element's name, written as a complete sentence ending in a period. // ParseSize converts a human-readable size ("2.5G") to bytes.
• A comment states a constraint the code can't show, a real-world fact, or the regression it guards. Never a narration of the next line, where the code came from, or why the change is correct. That last kind is review-speak and turns into noise the moment the change merges.
• The exception to the no-narration rule: a function with multiple logical steps uses short section comments to label each phase. "Validate input.", "Persist to database.", "Build response." Those segment the function; they don't narrate individual lines.
• Operational tone, written for someone maintaining or debugging the system. No conversational language, jokes, or speculative notes.
• Name the external source when there is one: the distro, the tool version, the kernel behavior. Naming the exact distro quirk the branch exists for beats "handle legacy services".
• Spell out arithmetic so numbers aren't magic: // reallocated 8 -> 40+40 capped 80; total 89 -> REPLACE_SOON.
• Match the file's comment density. A file with sparse comments doesn't get a narrated paragraph bolted onto one function.

Errors and logs

• Error strings: lowercase, no trailing punctuation, no "Error:" prefix. Chain context with colons or %w: syncing repo: connecting to source: connection refused. Say what was being attempted, not "failed to failed to".
• An error the operator will read should point at the fix when one is known: "set license.key in the config, or pass --license-key".
• Log messages: terse, lowercase, structured fields for the variables, no exclamation marks, no emoji. task executed with fields beats "Task was executed successfully!".
• Never log or print chatbot phrases: "Successfully completed!", "Oops!", "Something went wrong :(".

Svelte and UI copy

• Sentence case everywhere: buttons, labels, headings, menu items. "Import test", not "Import Test".
• Error states name what failed and what to do next. Not "Oops! Something went wrong" but "the server is unreachable; check that the service is running".
• Empty states say what will appear there or how to add the first item. No cutesy filler, no illustrations-with-quips tone.
• No exclamation marks in UI text. No emoji in buttons, headings, toasts, or placeholder text.
• Labels are literal. A field for a slug says "Slug", not "Your unique identifier". Tooltips explain the consequence of the setting, not restate its name.
• No marketing adjectives in product UI: "powerful", "seamless", "blazing fast". The interface should describe, not sell.

Docs and READMEs

• Say the thing directly. If a sentence can be replaced by a plainer one that says the same thing, replace it.
• A doc stands alone for its task. Don't make the reader open a second doc to use the first one; inline the few lines they need.
• Don't restate. If an example already appeared in an earlier section, later sections reference it, they don't duplicate it.
• Don't explain external systems. A doc about configuring a third-party integration covers how to configure it here and why, not how the third party's API works.
• Structure follows the sibling doc. Same heading shapes, same table format, same key: value conventions, so the docs read as one set.
• README covers how to build and test via the Makefile, actual usage, and real configuration. No badge walls, no "Features" bullet lists of adjectives, no roadmap promises.
• Headings in sentence case. No decorative emoji. No bold on every proper noun.

Commits and PRs

• Imperative, plain, specific: "Switch unit tests to testify", "Replace polling with retry backoff". No "This PR introduces...", no "Enhanced", no scope theater.
• The body states what changed and why, names the bug or behavior pinned, and stops. No summary tables of the diff, no "Testing" section that just says tests pass.

Language tells

• AI vocabulary: additionally, crucial, delve, enhance, fostering, garner, intricate, landscape (abstract), pivotal, robust, seamless, showcase, streamline, tapestry, testament, underscore, utilize, leverage. Use the plain word.
• Fancy ways to say "is": "serves as", "stands as", "boasts", "features". Say "is" or "has".
• "Not just X, but Y." State the point directly.
• Rule of three. Don't force ideas into groups of three; use the natural number.
• Filler: "in order to" becomes "to", "due to the fact that" becomes "because", "it is important to note that" gets deleted.
• Hedging stacks: "could potentially possibly" becomes "may".
• Abstract metaphor nouns: substrate, wedge, vector, nexus, primitive (as noun), harness (as metaphor), surface (as in "API surface"), scaffolding (as metaphor), paradigm, north star, flywheel. Pick the concrete word.
• Say what it does, not how it feels. "SQL you can read" names a feeling; ".toSQL() returns the exact string sent to the database" names a mechanism. If a sentence can't be restated as a fact, instruction, or number, cut it.
• Active voice. "The compiler validates queries", not "queries are validated". Passive only when the actor is unknown or doesn't matter.

Punctuation and style tells

• No em dashes, anywhere. Use periods or commas. Don't swap in parentheses or en dashes as a substitute; end the sentence instead.
• Colons before a list or example only, not as mid-sentence connectors.
• No arrow chains in prose ("A → B → fails"). Write the sentence. Arrows are fine inside code and code comments where they're the local idiom.
• Straight quotes, not curly.
• Bold sparingly. A bold lead-in that names an item and ends in a period is fine; a bold label with a colon that restates the line is a tell.
• No decorative emoji in headings, bullets, commits, or code.

Chat artifacts

Never let these into committed text: "I hope this helps!", "Let me know if...", "Great question!", "You're absolutely right!", "Found the smoking gun!", cutoff disclaimers like "while specific details are limited". Respond directly, write directly.