Humanize Beagle

Humanize

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

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

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

# 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

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

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

Match tone and length to the artifact type.

Fix Strategies by Category

Strategies for each finding type, organized by category. Each entry includes the fix approach, risk level, and before/after examples.

Table of Contents

• Content Patterns
• Vocabulary Patterns
• Formatting Patterns
• Communication Patterns
• Filler Patterns
• Code Docs Patterns

---

Content Patterns

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.

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.

Negative Parallelism

LLMs produce "Not just X, but also Y" and "Not X, but Y" constructions that add words without adding meaning. Delete the construction, keep the point.

Before:

This is not just a logging library, but also a comprehensive observability
framework that empowers developers to gain valuable insights.

After:

This is a logging library with structured output and trace correlation.

Rule of Three

LLMs overuse three-item lists ("adjective, adjective, adjective") to make superficial analyses appear comprehensive. Keep only items that carry specific meaning.

Before:

The event features keynote sessions, panel discussions, and networking opportunities.

After (keep only what's specific):

The event includes keynote sessions and breakout workshops.

Challenges-and-Prospects Formula

Rigid formula: "Despite its [positive words], [subject] faces challenges..." ending with vague positive assessment. Delete the wrapper, state the actual limitation with specifics.

Before:

Despite its robust architecture, the system faces challenges typical of
distributed environments. Despite these challenges, with its strategic
design and ongoing improvements, the platform continues to thrive.

After:

Known limitations: network partitions can cause stale reads for up to 30s.
See the consistency model docs for details.

---

Vocabulary Patterns

Copula Avoidance

LLMs substitute simple "is/are" with elaborate alternatives like "serves as", "stands as", "boasts", "features", "offers". Use the simple form.

Before:

feat: Leverage robust caching paradigm to facilitate seamless data retrieval

After:

feat: add response caching for faster reads

See references/vocabulary-swaps.md for the complete word swap table.

---

Formatting Patterns

Boldface overuse — 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.

Em dash overuse — Before:

The parser — which handles all input formats — validates each field — including nested objects — before returning.

After:

The parser validates each field (including nested objects) before returning. It handles all input formats.

Title case — Before:

## Strategic Negotiations And Global Partnerships

After:

## Strategic negotiations and global partnerships

---

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)

Vocabulary Swap Reference

Direct word replacements for high-signal and medium-signal AI vocabulary. Score density, not individual words — a cluster of 3+ AI words in proximity is one of the strongest AI tells.

High-Signal Words

These words spiked in frequency after 2022 and co-occur in AI-generated text.

Medium-Signal Words

Less distinctive individually, but meaningful in clusters.

Era Context

AI vocabulary shifts across model generations. Words co-occur: where one appears, others cluster nearby.

• 2023-mid 2024 (GPT-4 era): delve, tapestry, meticulous, intricate, garner, interplay, testament, vibrant
• Mid 2024-mid 2025 (GPT-4o era): bolstered, fostering, showcasing, align with, underscore, enhance
• Mid 2025+ (GPT-5 era): showcasing, highlighting, emphasizing, enhance (plus notability/attribution words)

What NOT to Flag

Do NOT treat these as AI indicators (high false-positive rate):

• Perfect grammar alone (many humans write well)
• Formal or academic prose (correlation is with specific words, not formality)
• Transition words alone (only a few specific transitions are AI-overused)
• Mixed casual/formal registers (common in technical fields)