humanize-beagle

---
name: humanize-beagle
description: Rewrite AI-generated developer text to sound human — fix inflated language, filler, tautological docs, and robotic tone. Use after review-ai-writing identifies issues.
disable-model-invocation: true
user-invocable: true
---

# Humanize

Apply fixes from a previous [review-ai-writing](../review-ai-writing/SKILL.md) run with automatic safe/risky classification. Builds on the writing principles in [docs-style](../docs-style/SKILL.md).

## Usage

Invoke the **humanize-beagle** skill with optional flags: `humanize-beagle [--dry-run] [--all] [--category <name>]`.

**Flags:**
- `--dry-run` - Show what would be fixed without changing files
- `--all` - Fix entire codebase (runs review with --all first)
- `--category <name>` - Only fix specific category: `content|vocabulary|formatting|communication|filler|code_docs`

## Instructions

### Hard gates

Advance past destructive or evidence-bound steps only when each **PASS** is true (commands and artifacts—not “I checked mentally”):

1. **G1 — Safe to edit files** — **PASS:** `git status --porcelain` is empty, **or** `git stash push -u -m "beagle-docs: pre-humanize backup"` exits 0.
2. **G2 — Review input is real JSON with expected shape** — **PASS:** `.beagle/ai-writing-review.json` exists **and** the file parses as JSON with a `git_head` key and a `findings` value that is an array (possibly empty). Use the `jq -e` command in step 3, or the same checks with `json.load` in Python. If this fails, stop with a parse/validation error—do not apply fixes.
3. **G3 — References before rewrites** — **PASS:** For each finding you will edit, the `references/*.md` files required by step 4 for that category/type are read in this session before you change text.
4. **G4 — Per-file validation** — **PASS:** Every modified file passes the step 8 check for its type; otherwise run `git checkout -- "$file"` for that file and do not list it as OK in the summary.
5. **G5 — Delete review file only on full success** — **PASS:** Run `rm .beagle/ai-writing-review.json` only when G4 holds for all files you are keeping unchanged from validation failures (aligns with step 10).

### 1. Parse Arguments

Extract flags from `$ARGUMENTS`:
- `--dry-run` - Preview mode only
- `--all` - Full codebase scan
- `--category <name>` - Filter to specific category

### 2. Pre-flight Safety Checks

```bash
# Check for uncommitted changes
git status --porcelain
```

If working directory is dirty, warn:
```text
Warning: You have uncommitted changes. Creating a git stash before proceeding.
Run `git stash pop` to restore if needed.
```

Create stash if dirty:
```bash
git stash push -u -m "beagle-docs: pre-humanize backup"
```

**G1 PASS:** Either the working tree was already clean, or the stash command exited 0.

### 3. Load Review Results

Check for existing review file:
```bash
cat .beagle/ai-writing-review.json 2>/dev/null
```

**If file missing:**
- If `--all` flag: Invoke the **[review-ai-writing](../review-ai-writing/SKILL.md)** skill with `--all` first
- Otherwise: Fail with: "No review results found. Invoke the review-ai-writing skill first."

**If file exists, validate JSON and freshness (G2):**
```bash
# Required shape: parseable JSON with git_head and findings array (may be empty)
jq -e 'has("git_head") and ((.findings // []) | type == "array")' .beagle/ai-writing-review.json >/dev/null 2>&1 \
  || { echo "Invalid or incompatible ai-writing-review.json"; exit 1; }

# Get stored git HEAD from JSON
stored_head=$(jq -r '.git_head' .beagle/ai-writing-review.json)
current_head=$(git rev-parse HEAD)

if [ "$stored_head" != "$current_head" ]; then
  echo "Warning: Review was run at commit $stored_head, but HEAD is now $current_head"
fi
```

If stale, prompt: "Review results are stale. Re-run review? (y/n)"

### 4. Load Reference Material

Read the appropriate reference files based on the findings being fixed:

- Read `references/vocabulary-swaps.md` when applying `ai_vocabulary_high` or `ai_vocabulary_low` fixes
- Read `references/fix-strategies.md` for strategy details and before/after examples for any category
- Read `references/developer-voice.md` for tone/register guidance when rewriting prose

Only load what you need — if fixing only vocabulary, skip the voice guide.

### 5. Filter Findings

If `--category` is set, filter findings to that category only.

Partition remaining findings by `fix_safety`:

**Safe Fixes** (auto-apply):
- `chat_leak` - Delete conversational artifacts
- `cutoff_disclaimer` - Delete knowledge cutoff references
- `filler_phrase` - Delete filler phrases
- `heading_restatement` - Delete restating first sentence
- `emoji_decoration` - Remove emoji from technical text
- `boldface_overuse` - Remove excessive bold formatting
- `ai_vocabulary_high` - Swap high-signal AI words
- `narrating_obvious` - Delete obvious code comments
- `synthetic_opener` - Delete "In today's..." openers
- `sycophantic_tone` - Delete or neutralize praise
- `vague_authority` - Delete unattributed claims
- `excessive_hedging` - Remove qualifiers
- `generic_conclusion` - Delete summary padding
- `copula_avoidance` - Use "is/are" naturally
- `rhetorical_device` - Delete rhetorical questions
- `em_dash_overuse` - Replace formulaic em dashes with commas, parentheses, or colons
- `thematic_break` - Remove horizontal rules before headings
- `title_case_heading` - Convert AI title-case headings to sentence case
- `curly_quotes` - Normalize curly quotes/apostrophes to straight
- `negative_parallelism` - Delete "Not just X, but also Y" filler constructions
- `challenges_and_prospects` - Delete "Despite its... faces challenges..." formulaic wrappers

**Needs Review Fixes** (require confirmation):
- `promotional_language` - Rewrite with specifics
- `formulaic_structure` - Restructure sections
- `synonym_cycling` - Pick consistent term
- `commit_inflation` - Rewrite commit scope
- `tautological_docstring` - Rewrite or delete docstring
- `exhaustive_enumeration` - Trim parameter docs
- `this_noun_verbs` - Rewrite docstring voice
- `ai_vocabulary_low` - Reduce cluster density
- `apologetic_error` - Rewrite error message
- `rule_of_three` - Simplify three-item lists used as filler comprehensiveness
- `inline_header_list` - Restructure boldfaced inline-header vertical lists
- `unnecessary_table` - Convert small tables to prose
- `regression_to_mean` - Restore specific facts replaced by vague praise

### 6. Apply Safe Fixes

If `--dry-run`:
```markdown
## Safe Fixes (would apply automatically)

| # | File | Line | Type | Action |
|---|------|------|------|--------|
| 1 | README.md | 3 | synthetic_opener | Delete "In today's rapidly evolving..." |
| 2 | src/auth.py | 15 | narrating_obvious | Delete "# Check if user exists" |
| 3 | README.md | 42 | ai_vocabulary_high | Replace "utilize" with "use" |
...
```

Otherwise, apply fixes grouped by file to minimize file I/O:

1. Sort findings by file, then by line number (descending, to avoid offset drift)
2. For each file, apply all safe fixes in reverse line order
3. For git artifacts (`git:commit:*`, `git:pr:*`), skip — these can't be auto-fixed. Report them for manual attention.

### 7. Handle Needs Review Fixes

If `--dry-run`, list them:
```markdown
## Needs Review Fixes (would prompt interactively)

| # | File | Line | Type | Original | Suggested |
|---|------|------|------|----------|-----------|
| 4 | README.md | 8 | promotional_language | "powerful, enterprise-grade solution" | "authentication library" |
...
```

Otherwise, for each fix, prompt interactively:

```text
[README.md:8] Promotional language: "powerful, enterprise-grade solution"
Suggested: "authentication library"
(y)es / (n)o / (e)dit / (s)kip all:
```

Track user choices:
- `y` - Apply this fix as suggested
- `n` - Skip this fix
- `e` - User provides custom replacement
- `s` - Skip all remaining interactive fixes

### 8. Validate Results

For each modified markdown file, verify basic validity:

```bash
# Check for broken markdown (unclosed code blocks, broken links)
# Simple check: matching ``` pairs
grep -c '```' "$file" | awk '{print ($1 % 2 == 0) ? "OK" : "WARNING: odd number of code fences"}'
```

For modified source files, check syntax is still valid:

**Python:**
```bash
python3 -c "import ast; ast.parse(open('$file').read())"
```

**TypeScript/JavaScript:**
```bash
npx -y acorn --ecma2020 "$file" > /dev/null 2>&1
```

If validation fails for any file, revert that file:
```bash
git checkout -- "$file"
echo "Reverted $file due to validation failure"
```

### 9. Report Results

```markdown
## Humanize Summary

### Applied Fixes
- [x] README.md:3 - Deleted synthetic opener
- [x] README.md:42 - Replaced "utilize" with "use"
- [x] src/auth.py:15 - Deleted obvious comment

### Interactive Fixes
- [x] README.md:8 - Rewrote promotional language (user approved)
- [ ] docs/guide.md:22 - Skipped by user

### Skipped (Git Artifacts)
- [ ] git:commit:abc1234 - Chat leak in commit message (amend manually)

### Validation
- README.md: OK
- src/auth.py: OK

### Diff Summary
```

```bash
git diff --stat
```

### 10. Cleanup

On successful completion (all validations pass):
```bash
rm .beagle/ai-writing-review.json
```

If any validation fails, keep the file and report:
```text
Review file preserved at .beagle/ai-writing-review.json
Fix issues and re-run, or restore with: git stash pop
```

## Core Principles

1. **Delete first, rewrite second.** Most AI patterns are padding. Removing them improves the text.
2. **Use simple words.** Replace "utilize" with "use", "facilitate" with "help", "implement" with "add".
3. **Keep sentences short.** Break compound sentences. One idea per sentence.
4. **Preserve meaning.** Never change what the text says, only how it says it.
5. **Match the register.** Commit messages are terse. READMEs are conversational. API docs are precise. Read `references/developer-voice.md` for the full register guide.
6. **Don't overcorrect.** A slightly formal sentence is fine. Only fix patterns that read as obviously AI-generated.
7. **Understand regression to the mean.** LLMs produce the most statistically likely output. Specific, unusual facts get replaced with generic, positive descriptions. When humanizing, restore specificity — replace vague praise with concrete details.
8. **Score density, not individual words.** AI vocabulary words co-occur. One or two may be coincidental; a cluster of 3+ is a strong AI tell.

## Example

Invoke the **humanize-beagle** skill with flags:

- `--dry-run` — preview all fixes without applying
- `--category vocabulary` — fix only vocabulary issues
- `--all` — full codebase scan and fix
- `--category filler --dry-run` — preview filler fixes only

## Rules

- Always load reference material before applying fixes (step 4); satisfy **G3** per finding
- Never modify files without a clean working tree or a successful stash (**G1**)
- Apply safe fixes in reverse line order to avoid offset drift
- Never auto-fix git artifacts (commits, PRs) — report them for manual action
- Validate every modified file before considering it done (**G4**)
- Revert files that fail validation
- Do not present the step 9 summary as “complete” until step 8 validation has passed for every file you are keeping
- Remove `.beagle/ai-writing-review.json` only after full success (**G5**); if validation failed partway, keep the file and follow step 10