unslop

What this skill does

# Unslop — Post-Generation Code Quality Cleanup

Reviews git diffs against 14 simplicity directives and proposes concrete fixes. Targets the specific failure mode of AI-generated code: correct but bloated.

## Core Philosophy

AI code generators produce code that is usually correct but systematically verbose. The model optimizes for *appearing thorough* — adding defensive checks, optional parameters, helper abstractions, and error handling for conditions that cannot occur. This isn't a bug; it's an alignment artifact. The model would rather include unnecessary code than risk missing something.

The result: code that works but is harder to read, has more state to track, and is more complex than necessary. This skill identifies and removes that accidental complexity.

**The test is simple: does removing this code change behavior?** If not, remove it.

## How to Detect Changed Code

Use git to find what changed. Try these in order:

1. **Branch diff** (most common): `git diff main...HEAD --name-only` — all changes on this branch
2. **Staged changes**: `git diff --staged --name-only` — about to be committed
3. **Unstaged changes**: `git diff --name-only` — modified but not staged
4. **Explicit files**: User passes `--files path1 path2` — skip detection

Filter out non-code files: lockfiles, `*.generated.*`, `vendor/`, `node_modules/`, images, fonts, `.min.*` files.

For the actual diff content per file: `git diff main...HEAD -- path/to/file.ts`

## The 14 Directives — Summary

| # | Directive | Red Flag |
|---|-----------|----------|
| 1 | Write skimmable code | Long functions requiring full read to understand, poor visual structure |
| 2 | Minimize possible states | Extra arguments, wider types than needed, boolean flags |
| 3 | Use discriminated unions | `type` field + separate checks vs. a single discriminated union |
| 4 | Exhaustively handle multi-type objects | `if/else` chains missing cases, no `default: assertNever()` |
| 5 | Trust the types | Null checks on non-nullable types, redundant `typeof` guards |
| 6 | Assert on load, be opinionated | Permissive defaults, late validation, `?? fallback` for required values |
| 7 | Remove changes not strictly required | Diff includes reformatting, renames, or moves unrelated to the task |
| 8 | Bias for fewer lines | Verbose constructs when concise alternatives exist |
| 9 | No complex or clever code | Nested ternaries, chained reduces, generic abstractions for single use |
| 10 | Don't over-split functions | Helpers called once, 3-line functions wrapping trivial logic |
| 11 | Early returns over nesting | `if/else` chains where early return would flatten the logic |
| 12 | Assert instead of try/catch or defaults | `try { } catch { return default }` hiding real errors |
| 13 | Keep argument count low | Functions taking 4+ parameters, passing unchanged values through |
| 14 | Don't make arguments optional if required | `arg?: Type` where every caller passes the argument |

For detailed guidance, examples, and before/after code for each directive, load **`references/code-quality-directives.md`**.

## Decision Tree — Which Reference to Load

**"I need detailed guidance on a specific directive"**
→ **`references/code-quality-directives.md`** — Full principle, reasoning, red flags, and before/after examples for all 14 directives.

**"I'm not sure if this is a real issue or a false positive"**
→ **`references/gotchas.md`** — Framework conventions, language idioms, test code exceptions, and cases where complexity is genuinely warranted.

**"I need both"**
→ Load both. The directives file is the primary reference; gotchas is the safety net.

## Output Format

Every review produces findings in this structure:

```
## Unslop Review

### Summary
- Files reviewed: N
- Findings: N (breakdown by directive)
- Estimated lines removable: N

### File: path/to/file.ts

1. **Directive #N: [Name]** — Lines L1-L2
   - What: [One sentence describing the issue]
   - Why: [The principle violated and the concrete cost]
   - Fix:
   ```ts
   [replacement code]
   ```

### Recommendations
- [Top 3 highest-impact simplifications across all files]
```

**Rules for findings:**
- Only flag code in the diff — unchanged code is out of scope
- Every finding needs a concrete fix — "consider simplifying" is not acceptable
- Check gotchas before finalizing — false positives destroy trust
- Group related findings that share a root cause
- Estimate lines removable per finding

## Workflow

### Small diffs (≤10 files)

1. Detect changed files via git
2. For each file: read contents, get diff, evaluate against directives
3. Load `references/code-quality-directives.md` for detailed guidance on flagged directives
4. Check `references/gotchas.md` before finalizing
5. Present report
6. Apply fixes → typecheck → lint → report (skip if `--check`)

### Large diffs (>10 files)

1. Detect changed files via git
2. Spawn `unslop-reviewer` subagent per file or batch of related files
3. Collect reports from subagents
4. Deduplicate and merge findings
5. Present consolidated report
6. Apply fixes sequentially → typecheck → lint → report (skip if `--check`)

## What This Skill Does NOT Do

- **Correctness** — Not checking if the code works. That's what tests are for.
- **Formatting** — Not checking style, indentation, or semicolons. That's the formatter's job.
- **Naming** — Not judging variable or function names. Too subjective, low ROI.
- **Performance** — Not profiling or benchmarking. See the `performance-optimization` skill.
- **Security** — Not scanning for vulnerabilities. Separate concern entirely.
- **Architecture** — Not redesigning the module structure. Just cleaning up within it.

This skill has one job: reduce accidental complexity in recently changed code.

## All Reference Files

| File | Content | Lines |
|------|---------|-------|
| **`references/code-quality-directives.md`** | Detailed per-directive guidance with before/after examples | ~900 |
| **`references/gotchas.md`** | False positive prevention, framework exceptions, language idioms | ~250 |