/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

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