---
name: perplexity-improver
description: Improve chapter perplexity score by rewriting AI-suspect sentences. Use after writing a chapter to reduce detectable AI patterns.
---

# Perplexity Improver Skill

Reduce AI-detectable patterns in chapters by rewriting low-perplexity sentences while preserving narrative integrity.

## Quick Start

```
/perplexity-improver story/chapters/chapitre-05.md
```

Multiple chapters can be analyzed in one run:
```
/perplexity-improver story/chapters/chapitre-01.md story/chapters/chapitre-02.md
```

## Performance Warning

⚠️ **The analysis script is SLOW** (several minutes for model loading and analysis).

- Accumulate several corrections before re-running
- Use at the end of a writing session, not after each edit

## When to Use

- After writing a chapter, before final validation
- When perplexity analysis shows a warning (⚠️)

## Supported Languages

| Code | Language | Techniques File |
|------|----------|-----------------|
| `fr` | Français | `references/rewriting-techniques-fr.md` |
| `en` | English | `references/rewriting-techniques-en.md` |

## Workflow

### Phase 1: Analyze Chapter

**1. Detect language** from chapter content (first 500 characters):
   - Identify language code (`fr`, `en`, etc.)
   - Load corresponding techniques file: `references/rewriting-techniques-{lang}.md`
   - If language not supported → report error and exit

**2. Run perplexity analysis** from the script directory (required for uv to find dependencies):
```bash
cd scripts/detection && uv run python detection.py ../../<path/to/chapter.md>
```

**Important**: The `uv run` command must be executed from `scripts/detection/` where the `pyproject.toml` is located.

**3. Extract from output:**
- Median perplexity score
- Warning status (median below threshold)
- Suspect rate (percentage of suspect sentences)
- List of suspect sentences sorted by ascending perplexity

### Phase 2: Evaluate Need

The script flags sentences using multiple criteria:
- **low_perplexity**: individually predictable sentence
- **low_std**: passage with uniform perplexity (no surprises)
- **adjacent_low**: extended stretch without friction
- **low_ppl_density**: cumulative boredom signal
- **forbidden_word**: AI-signal vocabulary

**Decision tree:**
- If no warning (⚠️) in output → **PASS**, report and exit
- If warning displayed (flagged rate > 25%) → proceed to Phase 3

**Priority**: Sentences with multiple flags (multi-flagged) should be rewritten first using techniques from `references/rewriting-techniques-{lang}.md`.

### Phase 3: Rewrite Sentences

Process sentences from lowest perplexity first (most predictable = most suspect).

For each suspect sentence:
1. **Locate** in original chapter
2. **Rewrite** using techniques from `references/rewriting-techniques-{lang}.md`
3. **Preserve** exact meaning and narrative function

**CRITICAL**: Verify that meaning is preserved and rewrites integrate naturally.

### Phase 4: Re-analyze

Run perplexity script on modified chapter.

Compare before/after:
- Median perplexity: target ≥ threshold (no warning)
- Suspect rate: target ≤ 20%
- Suspect sentence count: target reduction

**If still warning:**
- Iterate (max 3 loops)
- Try different rewriting techniques
- Focus on remaining lowest-perplexity sentences

### Phase 5: Finalize

Generate reports in `.work/`:
- `perplexity-report.md`: before/after stats, PASS/FAIL status
- `perplexity-changes.md`: each rewritten sentence with technique used

Ask for validation before applying changes to chapter file.

## Thresholds Reference

All thresholds are defined in `scripts/detection/detection.py` (constants at top of file).

## Interaction Style

- Show progress after each phase
- Present before/after comparisons
- Explain technique choices
- Ask for validation before applying changes to file