text-human — remove AI artifacts

Caution

AI pair-programming sessions leave fingerprints. Fake issue references (BUG-001, ISSUE-42), unicode long dashes, curly quotes, and comment blocks like // Added by AI or // Claude suggestion accumulate silently across commits. They break diffs, confuse reviewers, and signal “generated code” to anyone reading later.

Tip

One command, any scope. Pass a commit hash to process every changed file from that session, or pass a path for targeted cleanup. Everything after the first token becomes a custom instruction — no quotes needed. Parallel sub-agents handle large folders without blocking.

Quick reference

Field	Value
Command	`/brewtools:text-human`
Arguments	`<commit-hash\|path> [custom instructions]`
Model	sonnet
Context	session
Tools	Read, Write, Edit, Grep, Glob, Bash, Task, AskUserQuestion

When to use

After an AI-assisted commit — pass the hash, clean all touched files in one run
Before code review — strip obvious AI markers so reviewers focus on logic, not noise
Single file cleanup — path to one file runs directly, no delegation overhead
Folder-wide unicode pass — fix arrows and curly quotes across an entire package
Custom-rule pass — append instructions to override or extend defaults ("only fix unicode", "also remove @author tags")

Examples

# All files from a recent AI-assisted commit
/brewtools:text-human 3be67487

# Single service class
/brewtools:text-human src/main/java/com/example/OrderService.java

# Entire package
/brewtools:text-human src/main/java/services/

# Commit cleanup — preserve public API docs
/brewtools:text-human 3be67487 don't touch docs on public records

# Folder pass — only unicode and AI markers
/brewtools:text-human src/ only remove AI artifacts and fix unicode

# Add extra rule on top of defaults
/brewtools:text-human 3be67487 also remove all @author tags

No arguments? The skill asks: commit hash, file path, or folder path.

Flow

Scope resolution
Parses the first token as commit hash (7+ hex digits), file path, or folder path. Missing or ambiguous scope triggers AskUserQuestion — “entire project” always asks to narrow down.
File discovery
Commit mode: git diff —name-only hash^..hash, all text files. Path mode: recursive find excluding target/, node_modules/, build/, binaries, images, archives. Single file: straight to processing.
Language detection and block formation
Loads the matching language reference (Java/Kotlin, TypeScript/JS, Python) before classifying. Files split into 3–10 parallel blocks by complexity: simple config/data/text files go to haiku agents; source with logic, tests, and complex SQL go to sonnet agents.
Parallel execution
All Task calls fire in one message for true parallelism. Each sub-agent receives its block, the language reference, and any custom instructions prepended at highest priority. Custom instructions override defaults on conflict.
Aggregation and report
JSON results from all agents merge into a unified Humanization Report: total files, blocks used, haiku/sonnet split, comments removed, docs simplified, unicode fixed — per file and as totals. Files are edited in place; use git to revert.

Internals

What gets removed

Category	Pattern	Action
AI comment markers	`// Added by AI`, `// Claude suggestion`, `/* Suggested by */`	Delete
Fake issue refs	`BUG-001`, `FIX-123`, `ISSUE-42`	Delete (real project tickets kept)
Unicode long dash	U+2014	Replace with `--`
Unicode arrows	`→`, `←`, `⇒`	Replace with `->`, `<-`, `=>`
Unicode bullets/quotes	`•`, `"`, `"`, `'`, `'`	Replace with ASCII equivalents
Trivial docs	Javadoc/docstring restating method name	Delete
Obvious comments	`// Initialize the list`, `// Loop through items`	Delete
Formatting noise	3+ blank lines, trailing whitespace, `/* single line */`	Normalize

What gets kept

Preserved	Reason
”Why” comments	`// Retry 3x — flaky external API` explains non-obvious behavior
Public API docs	External contracts
Real ticket refs	`JIRA-456`, `GH-123` are project-specific
Structural SQL/YAML comments	Section organization
Complex algorithm explanations	Not trivially obvious from code

Block sizing

Files	Lines	Blocks	Agents
1–2	<200	1	direct
3–5	<500	3	parallel
6–10	500–1500	5	parallel
11–20	1500–3000	7	parallel
21+	3000+	10	parallel

Custom prompt handling: everything after the first arg token is prepended to every sub-agent prompt as CUSTOM INSTRUCTIONS (highest priority, override defaults). It wins over all default rules on conflict.

✨

Updating plugins

Use /brewtools:plugin-update to check and update the brewcode plugin suite in one command. See the FAQ for details.