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
dependencies	["docs-style","review-ai-writing"]

Humanize

Apply fixes from a previous review-ai-writing run with automatic safe/risky classification.

Usage

/beagle-docs: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

# Check for uncommitted changes
git status --porcelain

If working directory is dirty, warn:

Warning: You have uncommitted changes. Creating a git stash before proceeding.
Run `git stash pop` to restore if needed.

Create stash if dirty:

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:

cat .beagle/ai-writing-review.json 2>/dev/null

If file missing:

• If --all flag: Run /beagle-docs:review-ai-writing --all first
• Otherwise: Fail with: "No review results found. Run /beagle-docs:review-ai-writing first."

If file exists, validate JSON and freshness (G2):

# 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:

## 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:

## 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:

[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:

# 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:

python3 -c "import ast; ast.parse(open('$file').read())"

TypeScript/JavaScript:

npx -y acorn --ecma2020 "$file" > /dev/null 2>&1

If validation fails for any file, revert that file:

git checkout -- "$file"
echo "Reverted $file due to validation failure"

9. Report Results

## 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

git diff --stat

10. Cleanup

On successful completion (all validations pass):

rm .beagle/ai-writing-review.json

If any validation fails, keep the file and report:

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

# Preview all fixes without applying
/beagle-docs:humanize-beagle --dry-run

# Fix only vocabulary issues
/beagle-docs:humanize-beagle --category vocabulary

# Full codebase scan and fix
/beagle-docs:humanize-beagle --all

# Preview filler fixes only
/beagle-docs:humanize-beagle --category filler --dry-run

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