Humanize Ai Writing

Humanize

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

Usage

/beagle-docs:humanize-ai-writing [--dry-run] [--all] [--category ]

Flags:

Instructions

1. Parse Arguments

Extract flags from $ARGUMENTS:

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"

3. Load Review Results

Check for existing review file:

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

If file missing:

If file exists, validate freshness:

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

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

Needs Review Fixes (require confirmation):

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:

8. Validate Results

For each modified markdown file, verify basic validity:

# Check for broken markdown (unclosed code blocks, broken links)
Simple check: matching 

For modified source files, check syntax is still valid:
Python:

TypeScript/JavaScript:

If validation fails for any file, revert that file:

9. Report Results

10. Cleanup
On successful completion (all validations pass):

If any validation fails, keep the file and report:

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

Rules

# Preview all fixes without applying
/beagle-docs:humanize-ai-writing --dry-run
Fix only vocabulary issues
/beagle-docs:humanize-ai-writing --category vocabulary
Full codebase scan and fix
/beagle-docs:humanize-ai-writing --all
Preview filler fixes only
/beagle-docs:humanize-ai-writing --category filler --dry-run