Humanize

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

Usage

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

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"

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

Skill(skill: "beagle-docs:humanize")

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

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

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

Example

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

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

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

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

Rules

• Always load beagle-docs:humanize skill first
• Never modify files without a stash or clean working directory
• 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
• Revert files that fail validation
• Write JSON report before displaying summary
• Clean up JSON report only on full success

Reference Material

Humanize Developer Text

Fix AI-generated writing patterns in docs, docstrings, commit messages, PR descriptions, and code comments. Prioritize deletion over rewriting — the best fix for filler is removal.

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.
6. Don't overcorrect. A slightly formal sentence is fine. Only fix patterns that read as obviously AI-generated.

Fix Strategies by Category

Content Patterns

Before:

In today's rapidly evolving software landscape, authentication is a crucial
component that plays a pivotal role in securing modern applications.

After:

This guide covers authentication setup for the API.

Vocabulary Patterns

Word swap reference:

Before:

feat: Leverage robust caching paradigm to facilitate seamless data retrieval

After:

feat: add response caching for faster reads

Formatting Patterns

Before:

## Error Handling

**Error handling** is a **critical** aspect of building **reliable** applications.
The `handleError` function **catches** and **processes** all **runtime errors**.

After:

## Error Handling

The `handleError` function catches runtime errors and logs them with context.

Communication Patterns

Before:

# Great implementation! This elegantly handles the edge case.
# As of my last update, this API endpoint supports JSON.

After:

# Handles the re-entrant edge case from issue #42.
# This endpoint accepts JSON.

Filler Patterns

Before:

It's worth noting that the configuration file might potentially need to be
updated. Going forward, this could possibly affect performance.

After:

Update the configuration file. This affects performance.

Code Docs Patterns

Before:

def get_user(user_id: int) -> User:
    """Get a user.

    This method retrieves a user from the database by their ID.

    Args:
        user_id: The ID of the user to get.

    Returns:
        User: The user object.

    Raises:
        ValueError: If the user ID is invalid.
    """
    return db.query(User).get(user_id)

After:

def get_user(user_id: int) -> User:
    """Raises UserNotFound if ID doesn't exist in the database."""
    return db.query(User).get(user_id)

Developer Voice Guidelines

Good developer writing is:

• Conversational but precise. Write like you'd explain it to a colleague, but get the details right.
• Direct. State opinions. "Use X" not "You might consider using X".
• Terse where appropriate. Commit messages and code comments should be short. Don't pad them.
• Specific. Replace vague claims with concrete details, numbers, or examples.
• Consistent. Pick one term and stick with it. Don't cycle synonyms.

Register Guide

Applying Fixes

Safe Fixes (Auto-Apply)

These are mechanical and can be applied without human review:

• Delete chat leaks ("Certainly!", "Great question!")
• Delete cutoff disclaimers ("As of my last update")
• Delete filler phrases ("It's worth noting that")
• Delete heading restatements
• Remove emoji from technical docs
• Remove excessive bold formatting
• Swap high-signal AI vocabulary (utilize -> use)
• Delete "As we can see" / "Let's take a look at"
• Delete narrating-obvious comments

Needs Review Fixes (Interactive)

These require a human to verify the replacement preserves intent:

• Rewriting promotional language (may need domain knowledge)
• Fixing synonym cycling (need to pick the right term)
• Rewriting tautological docstrings (need to decide what's actually worth documenting)
• Trimming exhaustive parameter docs (need to decide which params are non-obvious)
• Rewriting commit messages (scope judgment)
• Restructuring formulaic sections (may change document flow)
• Fixing apologetic error messages (wording matters for UX)