slop-grader

# slop-grader



[](https://www.npmjs.com/package/@lukstei/slop-grader)
[](https://www.npmjs.com/package/@lukstei/slop-grader)
[](https://www.npmjs.com/package/@lukstei/slop-grader)
[](https://opensource.org/licenses/MIT)

Rule-based slop grader for text files, powered by [Jev](https://typesafe.ai).
Runs every rule against every line in parallel. No skimming, no missed lines.

- [How it works](#how-it-works)
- [Features](#features)
- [FAQ](#faq)
- [Quick Start](#quick-start)
- [Rulesets](#rulesets)
- [CLI Reference](#cli-reference)
- [Output Formats](#output-formats)
- [Development](#development)
- [Changelog](#changelog)
- [Contributing](#contributing)
- [Roadmap](#roadmap)

## How it works

`slop-grader` runs as a two-step loop: grade text with the CLI, then paste the output to your AI agent to plan the improvements.

### 1. Grade the document

Run `slop-grader` on a document like [`examples/slop.md`](examples/slop.md):

```sh
npx @lukstei/slop-grader@latest -r no-ai-slop examples/slop.md
```

<img src="assets/terminal.png" alt="Terminal output" width="550" />

### 2. Fix with an AI agent

Pass the output to your AI agent:

- The agent distinguishes real violations from false positives and generates concrete replacements ([Example with Gemini 3.8 Flash](examples/plan.md)):
  > **Line 1 — `banned_word`**
  > - **Original:** `# 🚀 The Ultimate Paradigm Shift in Modern Data Architecture`
  > - **Fix:** `# Modern Data Architecture`
  > - **Reason:** Removes the banned phrase "paradigm shift" and decorative emoji.
  >
  > **Line 7 — `binary_contrast` + `faux_insight` + `colon_reveal`**
  > - **Original:** `What most people get wrong about databases is simple: it's not about speed, it's about trust.`
  > - **Fix:** `Database design balances speed and trust.`
  > - **Reason: