skills/unslop/SKILL.md

---
name: unslop
description: 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.