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."