humanize-beagle

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, reve