slop-grader

# slop-grader


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


Rule-based slop grader for text files, powered by [Jev](https://typesafe.ai).

## 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)):
  ```markdown
  ### 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` + `fake_profound_kicker`
  - **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:** Removes rhetorical framing and fake insight.
  ```
- After your review the plan is applied to produce an [improved document](examples/slop-improved.md).

## FAQ

<details>
<summary><strong>How does evaluation work?</strong></summary>

Evaluation separates line-level checks (spotting specific patterns or phrases) from document-level checks (evaluating tone or overall structure).

Documents have hundr