# Remediation playbook

> Per-tell clean fixes, what to remove or replace, and how before or after demos illustrate the preferred outcome.

- Repository: yetone/kill-ai-slop
- GitHub: https://github.com/yetone/kill-ai-slop
- Human docs: https://grok-wiki.com/public/docs/yetone-kill-ai-slop-c0d8c9670cbb
- Complete Markdown: https://grok-wiki.com/public/docs/yetone-kill-ai-slop-c0d8c9670cbb/llms-full.txt

## Source Files

- `skill/references/fixes.md`
- `skill/references/taxonomy.md`
- `website/src/data/demos.ts`
- `website/src/components/BeforeAfter.astro`
- `skill/SKILL.md`

---

---
title: "Remediation playbook"
description: "Per-tell clean fixes, what to remove or replace, and how before or after demos illustrate the preferred outcome."
---

`skill/references/fixes.md` is the remediation source for kill-ai-slop: 23 numbered before→after patterns the agent skill applies in workflow step **5. Fix**, after scan, triage, and a user-visible report. Patterns are directions, not find-and-replace rules—adapt to project tokens and framework, and prefer one shared token or component edit over every call site.

<Note>
The standalone scanner (`node scripts/scan.mjs`) never edits files. Remediation runs only through the agent skill (propose or apply after the user chooses groups). Re-run the scanner after fixes to confirm hit counts drop, and note intentional leftovers with a reason.
</Note>

## Role in the skill workflow

| Stage | Surface | Remediation role |
| --- | --- | --- |
| Scan | `scripts/scan.mjs` | Map hits only; no edits |
| Triage | `references/taxonomy.md`, `references/detection.md` | Slop vs intentional; false positives |
| Report | Skill output | Tell + `file:line` + one-line proposed fix; wait for user |
| Fix | **`references/fixes.md`** | Minimal change that removes the tell |

Report lines already point at the fix direction, for example:

```text
slop  src/Hero.tsx:12   indigo→violet gradient        → one solid accent
slop  src/Hero.tsx:31   gradient-clip headline        → solid ink, scale up
slop  src/Note.tsx:8    border-l-4 callout ×3         → 1 aside, rest is body
slop  copy.md:1         "not just X — it's Y"         → say the specific thing
```

## Order of operations

From `fixes.md`:

1. **Design tokens / theme first** — colors, radius, fonts. Many hits disappear at once.
2. **Components**, then one-off call sites.
3. **Copy** last.

Skill-level constraints while applying fixes:

- Prefer shared tokens/components over every call site.
- Never invent new brand colors; if a palette must change, propose neutrals + the project’s existing accent and let the user confirm.
- Keep copy meaning; make it specific, do not only delete.
- Small, reviewable diffs; no new dependencies; no mass-edit before the report is accepted.
- Verify visually when a dev server exists—a cleaner scan is not the same as a better page.

## Principles on every fix

Held by `skill/SKILL.md` for every remediation:

1. Decide before you decorate.
2. One accent, one voice.
3. Hierarchy from scale and space (not colored words or font swaps).
4. Subtract first.
5. Specific beats punchy in copy.
6. Decoration (icons, badges, callouts) must mean something.

## Before / after demos (field guide)

The Astro field guide illustrates preferred outcomes with plain-HTML specimens in `website/src/data/demos.ts`. Each entry is `{ before, after }` keyed by demo id. Styles live under `.demo-<id>` in `styles/demos.css`.

`website/src/components/BeforeAfter.astro` loads `demos[id]` and renders a Slop / Clean toggle:

- Props: `id` — must exist in the demos map or the component throws `No demo for id "…"`.
- Stage shows one pane at a time (`data-show="before" | "after"`); both panes share a grid cell so height does not jump.
- Labels: **Slop** / **Clean** (localized via `<T>`); tags **SLOP** / **CLEAN** on the stage.
- `after` panes follow the same rules as the skill: one accent, no gradient chrome, hierarchy from scale + space, mono for code only, no decorative emoji/badges.

| Demo id (`demos.ts`) | Tell # | Taxonomy name |
| --- | --- | --- |
| `indigo-violet-gradient` | 01 | Indigo→violet gradient |
| `gradient-text` | 02 | Gradient headline text |
| `warm-cozy-palette` | 03 | Warm "cozy" palette |
| `default-semantic-palette` | 04 | Default semantic palette |
| `serif-emphasis` | 07 | Serif-italic on one word |
| `serif-body-misuse` | 08 | Serif where sans belongs |
| `decorative-text-lines` | 09 | Decorative strikes & highlights |
| `highlighted-keywords` | 10 | Highlighted keywords |
| `ai-copy-tics` | 11 | AI copywriting voice |
| `emoji-everywhere` | 12 | Emoji everywhere |
| `status-dot-glow` | 13 | Glowing status dot |
| `left-border-callout` | 14 | Rounded card, colored left border |
| `pastel-icon-tiles` | 15 | Rounded-square icon tiles |
| `over-rounded-glass` | 16 | Max radius + glassmorphism |
| `oversized-shadow` | 17 | Oversized drop shadow |
| `badge-spam` | 19 | Badge & pill spam |
| `feature-grid` | 22 | All-caps card grid |

Tells **05, 06, 18, 20, 21, 23** have fix patterns in `fixes.md` / taxonomy but no demo keys in the supplied `demos.ts` record.

## Per-tell clean fixes

Patterns below are condensed from `skill/references/fixes.md` and the taxonomy fix lines. Diffs use Tailwind-style class examples; rewrite to CSS variables, design tokens, or framework equivalents as needed.

### Color

#### 01 · Indigo→violet gradient

| | |
| --- | --- |
| **Remove / replace** | `from-indigo-* to-purple/violet/*` chrome; colored glow shadows (`shadow-purple-500/50`) |
| **Clean** | One solid accent (`bg-[--accent]`) |
| **If a gradient stays** | Single hue, low contrast, justified; drop the glow |

```diff
- class="bg-gradient-to-r from-indigo-500 to-purple-500 shadow-lg shadow-purple-500/50"
+ class="bg-[--accent]"
```

**Demo:** `indigo-violet-gradient` — gradient CTA + “✨ AI-POWERED” → solid card, plain eyebrow, solid button.

#### 02 · Gradient headline text

| | |
| --- | --- |
| **Remove** | `bg-clip-text text-transparent` rainbow fills on headings |
| **Clean** | Solid ink; impact via size/weight, not fill |

```diff
- <h1 class="bg-gradient-to-r from-indigo-500 to-pink-500 bg-clip-text text-transparent">
+ <h1 class="text-[--ink]">
```

**Demo:** `gradient-text` — gradient heading → solid heading; subcopy unchanged.

#### 03 · Warm "cozy" palette

| | |
| --- | --- |
| **Remove** | Amber/stone wash (`bg-[#fdf6ec]`, `text-amber-900`, `border-amber-200`) as the base |
| **Clean** | Near-neutral paper/ink/rule; one warm accent on a single element |
| **Process** | Propose neutrals; user confirms before global apply |

```diff
- bg-[#fdf6ec] text-amber-900 border-amber-200
+ bg-[--paper] text-[--ink] border-[--rule]
```

**Demo:** `warm-cozy-palette` — amber “cozy workspace” card → neutral workspace with specific subcopy.

#### 04 · Default semantic palette

| | |
| --- | --- |
| **Remove** | Framework rainbow chips (`blue-50/700`, `green-50/700`, `amber-50/700`, `red-50/700`) as unrelated candy colors |
| **Clean** | Neutrals + at most one or two intentional semantics from the brand palette |

```diff
- <span class="bg-blue-50 text-blue-700">Info</span>
- <span class="bg-green-50 text-green-700">Success</span>
- <span class="bg-amber-50 text-amber-700">Warning</span>
- <span class="bg-red-50 text-red-700">Error</span>
+ <span class="chip">Info</span> <span class="chip">Warning</span>
+ <span class="chip chip--ok">Success</span>
+ <span class="chip chip--danger">Error</span>
```

**Demo:** `default-semantic-palette` — multi-color chips → neutral chips with sparse ok/err markers.

#### 05 · One-hue status box

| | |
| --- | --- |
| **Remove** | Border + text + tint all one hue (`border-red-500 bg-red-500/10 text-red-500`) |
| **Clean** | Neutral surface + rule; state in a bold word; one muted accent optional |

```diff
- <div class="border border-red-500 bg-red-500/10 text-red-500 rounded p-3">
-   Something went wrong.
- </div>
+ <div class="border border-[--rule] bg-[--surface] text-[--ink] rounded p-3">
+   <b>Error</b> — something went wrong.
+ </div>
```

#### 06 · Gradients as atmosphere

| | |
| --- | --- |
| **Remove** | Page-level radial/atmosphere gradients; gradient card surfaces |
| **Clean** | One flat background; depth via hairline border (and restrained shadow if needed) |
| **If a glow stays** | Point it at one element, not fill the void |

```diff
- <body class="bg-[radial-gradient(circle_at_top,#1e293b,#020617)]">
-   <div class="rounded-2xl bg-gradient-to-b from-white/10 to-white/0 …">
+ <body class="bg-[--bg]">
+   <div class="rounded-[--radius] bg-[--card] border border-[--rule]">
```

### Type

#### 07 · Serif-italic on one word

| | |
| --- | --- |
| **Remove** | Mixed voice: serif italic accent word in a sans headline |
| **Clean** | Weight/position emphasis; one family voice |

```diff
- The editor that <em class="font-serif italic text-indigo-600">actually</em> ships.
+ The editor that <b>ships</b>.
```

**Demo:** `serif-emphasis` — `<em>200ms</em>` → `<b>200ms</b>`.

#### 08 · Serif where sans belongs

| | |
| --- | --- |
| **Remove** | Display serif (e.g. Playfair) as UI/body on tools/SaaS |
| **Clean** | Project UI sans tokens; text serif only for a true editorial voice |

```diff
- font-family: "Playfair Display", serif;
+ font-family: var(--font-sans);
```

**Demo:** `serif-body-misuse` — serif metrics panel → sans panel; numbers unchanged.

#### 09 · Decorative strikes & highlights

| | |
| --- | --- |
| **Remove** | `<s>`, decorative `<u>`, `<mark>` used as emphasis, not real edit/link/annotation |
| **Clean** | Plain heading; structure carries emphasis |
| **Keep when legitimate** | Strike for real edits, underline for links, highlight for real annotation |

```diff
- <h1>The <s>old</s> <mark>new</mark> way to <u>ship</u>.</h1>
+ <h1>A faster way to ship.</h1>
```

**Demo:** `decorative-text-lines` — strike/underline/mark headline → plain specific headline.

### Copy

#### 10 · Highlighted keywords

| | |
| --- | --- |
| **Remove** | Scattered colored/bold mid-sentence keywords |
| **Clean** | Specific sentences; at most one accented phrase |

```diff
- Our <span class="text-indigo-600 font-semibold">revolutionary</span> platform helps
- <span class="text-pink-600 font-semibold">ambitious</span> teams move faster.
+ A project tracker for engineering teams. It updates issues from your commits.
```

**Demo:** `highlighted-keywords` — multi-span hype paragraph → concrete product description.

#### 11 · AI copywriting voice

| | |
| --- | --- |
| **Remove** | “It’s not just X — it’s Y”, “Say goodbye to…”, punchy triads, em-dash drama without specifics |
| **Clean** | Concrete nouns, numbers, consequences |

```diff
- It's not just an editor — it's a movement. Say goodbye to friction.
+ A code editor. Opens in under a second, ~half the memory of Electron editors.
```

**Demo:** `ai-copy-tics` — movement/friction/triad block → measured product facts.

#### 12 · Emoji everywhere

| | |
| --- | --- |
| **Remove** | Emoji on every heading, button, bullet |
| **Clean** | No decorative emoji; keep one only when it carries real information (e.g. status) |

```diff
- <h2>🚀 Why you'll love it</h2>
+ <h2>Why teams pick it</h2>
```

**Demo:** `emoji-everywhere` — emoji list → specific measurable bullets.

### Components

#### 13 · Glowing status dot

| | |
| --- | --- |
| **Remove** | `animate-ping` halo, glow shadow, inflated gem for a binary state |
| **Clean** | Small flat single-color dot + word |

```diff
- <span class="relative flex h-3 w-3">
-   <span class="animate-ping absolute … bg-green-400 opacity-75"></span>
-   <span class="relative rounded-full h-3 w-3 bg-green-500 shadow-lg shadow-green-500/50"></span>
- </span> Ready
+ <span class="inline-block h-2 w-2 rounded-full bg-[--ok]"></span> Ready
```

**Demo:** `status-dot-glow` — glowing live indicator → flat dot + “Online”.

#### 14 · Rounded card, colored left border

| | |
| --- | --- |
| **Remove** | Stacked `border-l-4` rounded callouts used as universal decoration |
| **Clean** | Body prose for list content; at most one real `<aside>` |

```diff
- <div class="border-l-4 border-indigo-500 rounded-lg bg-indigo-50 p-4">Note …</div>
- <div class="border-l-4 border-amber-500 rounded-lg bg-amber-50 p-4">Tip …</div>
+ <p>… the note, inline as normal prose …</p>
+ <aside class="note">Beta: exports may change format before 1.0.</aside>
```

**Demo:** `left-border-callout` — four colored call rows → plain list with the same facts.

#### 15 · Rounded-square icon tiles

| | |
| --- | --- |
| **Remove** | Decorative rounded tile + vague one-liner feature grid |
| **Clean** | Labelled list with real specifics; icon only if it carries meaning |

```diff
- <div class="rounded-xl bg-indigo-100 p-2"><Icon/></div><h3>Fast</h3><p>Very fast.</p>
+ <li><b>Fast</b> — cold start in 180 ms, measured on a 2020 laptop.</li>
```

**Demo:** `pastel-icon-tiles` — three glyph tiles → plain list with measurements.

#### 16 · Max radius + glassmorphism

| | |
| --- | --- |
| **Remove** | `rounded-full`, `backdrop-blur`, translucent panes as default chrome |
| **Clean** | One small site-wide radius; solid card + rule border |

```diff
- class="rounded-full backdrop-blur bg-white/10 border border-white/20"
+ class="rounded-[--radius] bg-[--card] border border-[--rule]"
```

**Demo:** `over-rounded-glass` — glass pill “Upgrade now” → flat card, specific plan copy, solid CTA with price.

#### 17 · Oversized drop shadow

| | |
| --- | --- |
| **Remove** | Room-sized soft shadows (`0 16px 80px…`); tinted glow shadows |
| **Clean** | Hairline and/or tight contact shadow; colorless; never larger than the element |

```diff
- box-shadow: 0 16px 80px 10px rgba(0,0,0,0.36);
+ border: 1px solid var(--rule);
+ box-shadow: 0 1px 2px rgba(0,0,0,0.06), 0 4px 10px -6px rgba(0,0,0,0.1);
```

Related: tell **01** purple glow-shadow; tell **13** status-dot halo.

**Demo:** `oversized-shadow` — fog panel → hairline + tight contact shadow caption.

#### 18 · Corners that don't nest

| | |
| --- | --- |
| **Remove** | Same large radius on outer and inner children |
| **Clean** | `inner ≈ outer − padding`, or no inner rounding |

```diff
- <div class="rounded-2xl p-3"><div class="rounded-2xl">…</div></div>
+ <div class="rounded-2xl p-3"><div class="rounded-lg">…</div></div>
```

#### 19 · Badge & pill spam

| | |
| --- | --- |
| **Remove** | Decorative “✨ New / 🔥 Popular / β Beta / PRO” pills |
| **Clean** | At most a real status (e.g. version) |

```diff
- <h1>Dashboard</h1><Pill>✨ New</Pill><Pill>🔥 Popular</Pill><Pill>β Beta</Pill>
+ <h1>Dashboard</h1><span class="ver">v2.1</span>
```

**Demo:** `badge-spam` — four pills → `v2.1` only.

#### 20 · AI-drawn SVG icons

| | |
| --- | --- |
| **Remove** | Crude model-sketched SVG blobs / primitive mascots shipped as the mark |
| **Clean** | Real icon (designer or refined image-model asset); no bare letter fallback as the brand |

```diff
- <svg viewBox="0 0 48 48"><circle cx="24" cy="24" r="20"/><circle cx="18" cy="20" r="2"/>…</svg>
+ <img src="/icon.svg" alt="" />
```

#### 21 · Icon in a tint of itself

| | |
| --- | --- |
| **Remove** | `bg-{color}/10` tile wrapping `text-{color}` icon |
| **Clean** | Icon inherits ink; if a container is needed, use a deliberate opaque surface |

```diff
- <div class="rounded-lg bg-blue-500/10 p-2"><Icon class="text-blue-500"/></div>
+ <Icon class="text-[--ink]"/>
```

#### 22 · The all-caps card grid

| | |
| --- | --- |
| **Remove** | Equal-weight icon + ALL-CAPS label + one-liner card grids |
| **Clean** | Lead with the single most important point, fully told |

```diff
- <div class="grid grid-cols-3 gap-8"> …6 icon+CAPS-label+one-liner cards… </div>
+ <p class="lead">It replaces your standups.</p>
+ <p>Every morning it reads yesterday's commits and PRs and writes the team a
+ three-line summary.</p>
```

**Demo:** `feature-grid` — caps feature cards (FAST / SECURE / SIMPLE / SCALABLE…) as the slop specimen.

#### 23 · The tasteful terminal

| | |
| --- | --- |
| **Remove** | Site-wide mono + near-black + amber “terminal UI” chrome and decorative ASCII frames |
| **Clean** | Monospace reserved for code; terminal metaphor only when the product needs it |

```diff
- <body class="font-mono bg-[#0a0a0a] text-amber-400">
-   <pre>  ╔══════════════╗
-          ║  WELCOME  ║
-          ╚══════════════╝…
```

## Quick lookup: remove → replace

| # | Tell | Primary remove | Primary replace |
| --- | --- | --- | --- |
| 01 | Indigo→violet gradient | Multi-hue gradient + glow | Solid `--accent` |
| 02 | Gradient headline | `bg-clip-text` rainbow | Solid `--ink`, scale/weight |
| 03 | Warm cozy palette | Amber/stone base wash | Neutral paper/ink + one accent |
| 04 | Default semantic palette | Framework color chips | Palette-derived chips |
| 05 | One-hue status box | Mono-hue border/bg/text | Neutral box + word state |
| 06 | Atmosphere gradients | Page/card gradient fog | Flat bg + hairline |
| 07 | Serif-italic word | Mixed serif italic | Bold / structure |
| 08 | Serif as UI | Display serif body | `--font-sans` |
| 09 | Decorative marks | `<s>`/`<u>`/`<mark>` drama | Plain structure |
| 10 | Highlighted keywords | Scattered color spans | Specific prose |
| 11 | AI copy voice | Not-just-X / triads | Concrete facts |
| 12 | Emoji everywhere | Decorative emoji | Specific labels |
| 13 | Glowing status dot | Ping + halo shadow | Flat dot + word |
| 14 | Left-border callouts | Stacked admonition cards | List / one aside |
| 15 | Pastel icon tiles | Tile + vague line | Specific list items |
| 16 | Over-round glass | Full radius + blur pane | Small radius solid |
| 17 | Oversized shadow | Huge soft blur | Hairline / tight shadow |
| 18 | Nested corners | Same radius all layers | outer − padding |
| 19 | Badge spam | Decorative pills | Real status only |
| 20 | AI SVG icons | Crude generated SVG | Refined real icon |
| 21 | Icon self-tint | Tint tile wrapper | Ink icon alone |
| 22 | Caps card grid | Equal CAPS cards | One lead story |
| 23 | Tasteful terminal | Mono site chrome | Mono for code only |

## Verification after apply

<Steps>
  <Step title="Re-scan">
    Run `node scripts/scan.mjs <root>` (or `--json`) and confirm targeted tell counts dropped.
  </Step>
  <Step title="Account for intentional hits">
    Document any remaining hits kept on purpose (brand gradient, deliberate emoji status, real annotation markup).
  </Step>
  <Step title="Visual check">
    If a dev server exists, compare the live UI to the field-guide Clean demos for the same tell—scan pass ≠ better page.
  </Step>
</Steps>

## Related pages

<CardGroup>
  <Card title="Apply clean fixes" href="/apply-clean-fixes">
    Map scanner hits to this playbook, choose propose vs apply in an agent host, and confirm the clean alternative.
  </Card>
  <Card title="Detection patterns" href="/detection-patterns">
    Code-level signals that produce the hits this playbook remediates.
  </Card>
  <Card title="Slop taxonomy" href="/slop-taxonomy">
    What each tell is, why it reads as machine-made, and shared taxonomy language.
  </Card>
  <Card title="Skill workflow" href="/skill-workflow">
    Scan → triage → report → fix lifecycle and the no silent-edit rule for the scanner.
  </Card>
  <Card title="Catalogue and demos data" href="/catalogue-data-reference">
    Demo HTML payloads and catalogue shapes used by `BeforeAfter` and the field guide.
  </Card>
  <Card title="Run the field guide site" href="/run-field-guide-site">
    Preview Slop/Clean demos locally via the Astro field guide.
  </Card>
</CardGroup>