text-human — universal AI artifact humanizer
Caution
Humanization targets surface artifacts such as self-attribution comments and repetitive prose. Ticket IDs, Unicode and comments can carry real meaning; appearance alone does not prove fabrication or justify changing program behavior.
Tip
One command, any content. Pass a commit hash, a file, a folder, or paste the text inline. The skill detects which domain it is dealing with, picks a matching flow, and runs a two-pass model: strip validated AI tells first, then a gated injection of human style fit for that domain.
Quick reference
| Field | Value |
|---|---|
| Command | /brewtools:text-human |
| Arguments | [prompt] [path|commit|folder|text] [custom instructions] |
| Model | sonnet (haiku for simple blocks in mixed flow) |
| Context | session |
| Tools | Read, Write, Edit, Grep, Glob, Bash, Agent, AskUserQuestion |
When to use
| Situation | Command |
|---|---|
| After an AI-assisted commit — clean all touched files (current worktree content at those paths, not the historical commit blob) | /brewtools:text-human 3be67487 |
| Before code review — strip obvious AI markers so reviewers focus on logic | /brewtools:text-human src/main/java/services/ |
| JavaDoc / API docs — remove trivial param restates, keep contracts | /brewtools:text-human clean the javadoc in PaymentApi.java |
| README / guide — fix metronomic prose, trim scaffolding phrases | /brewtools:text-human docs/getting-started.md |
| Reddit or Slack reply — add register-fit casual voice | /brewtools:text-human review this reddit reply: <text> |
| Published blog post or essay — add burstiness and real stance | /brewtools:text-human humanize this blog post: <text> |
| Folder-wide unicode and marker pass — strip only, no inject | /brewtools:text-human src/ only strip AI artifacts, no inject |
| Custom rule on top of defaults | /brewtools:text-human 3be67487 also drop all @author tags |
Examples
# Code flow -- strip AI tells, normalize unicode, inject OFF
/brewtools:text-human src/main/java/com/example/OrderService.java
# JavaDoc clean-only sub-profile
/brewtools:text-human clean the javadoc in PaymentApi.java
# Commit -- mixed flow routes each changed file to its domain
/brewtools:text-human 3be67487
# Reddit reply -- casual injection, sparse emoji, lowercase
/brewtools:text-human review this reddit reply: <text>
# Blog post -- burstiness + real stance
/brewtools:text-human humanize this blog post: <text>
# Folder -- mixed flow, parallel blocks
/brewtools:text-human src/main/java/services/
# Custom prompt overrides defaults (scope + rule)
/brewtools:text-human src/ only strip AI artifacts, no inject
/brewtools:text-human 3be67487 also drop all @author tags
No arguments? The skill asks: commit hash, file path, folder, or paste text.
Flow
- Phase 0 — Greedy flow detection
Before any processing the skill parses the argument, picks exactly ONE flow from context, and announces it:
Flow: <name> — <one-line why>. Detection priority: explicit intent keywords (RU+EN) first, then path/extension, then content sniff. Only that flow file and the pattern sections it needs are loaded (lazy — not everything at once). - Argument parsing
The first token is parsed as scope when it resolves to an existing path or a 7+ hex git hash; the rest becomes a custom prompt. Otherwise the whole input is a custom prompt (inline text to humanize or intent description). No args triggers
AskUserQuestionas fallback. The custom prompt both selects/overrides the flow and adds custom rules at highest priority. - Clean-tree precondition
Before the first edit on any writing flow, the skill runs
git status —porcelainover the resolved target paths only — there is no backup, so git is the only undo. Clean → proceeds. Dirty → oneAskUserQuestionlisting the dirty paths (proceed on them / process only the clean ones / abort); this replaces, not adds to, the flow-detection question. Not a git repo → the skill says so and requires an explicit go-ahead. Inline text and other non-file input skip this — nothing on disk changes. - PASS 1 — Strip
Validated AI tells are removed per the tiered pattern catalog. HIGH-tier universals (chat scaffolding, self-attribution comments, prompt residue, unicode normalization in prose and code comments) act on single hits. Unicode inside a string literal, regex, or identifier is never rewritten — it is surfaced instead, since normalizing it could change program behavior. MED density-signals act only when several co-occur in a cluster. Behavior-changing items — hallucinated refs, fabricated tickets, try/except-everywhere — are surfaced for review, never auto-edited.
- PASS 2 — Inject (gated)
Human style is applied for the detected domain. HARD-OFF for code and API/formal docs. For docs, commits, social, and articles the injection is tuned by domain: burstiness weight, contraction frequency, stance, emoji policy. Global guard: never injects typos, errors, or fabricated references in any flow.
- Parallel execution (mixed flow)
Commit or folder scope uses bounded mixed-flow blocks, with haiku for simple content and sonnet for logic, tests or complex SQL. Main launches
Agentcalls together and supplies resolved absolute rule paths and custom instructions. Preservation constraints still apply. A commit selects changed paths; edits affect current worktree content after the scoped clean-tree gate. - Humanization Report
Results merge into a report of flow, scope, processed files/blocks, model split, strip/inject counts and behavior-changing items surfaced for review. Files are edited in place; review the resulting diff.
Delegation (mixed flow)
Functional preservation overrides cosmetic cleanup. Keep meaningful private/internal and test
contracts, fixture assumptions, tool-consumed docs and doctests. Preserve GIVEN/WHEN/THEN/AND
and Arrange/Act/Assert comments, plus lint, type, security, build, license and coverage directives
byte-for-byte, including unexplained noqa or ESLint suppressions. Missing reasons are surfaced.
A cosmetic pass does not migrate types or APIs, remove/narrow suppressions, convert useful JavaDoc into ordinary comments, or change debug output. Such changes require separate explicit scope and relevant checks. Real tickets remain regardless of ID pattern; removal requires proof that an ID was invented and resolves to no real ticket in the actual tracker/provenance. Missing access or uncertainty is reported rather than guessed away.
Warning
A big task handed to one agent = an agent gone for an hour. You cannot observe it, you cannot correct it, and it usually drifts off-target. In the mixed flow one subagent = one block of ~5 files, ~10 steps. A large commit or folder is split into N blocks, all spawned in a single message.
Every block prompt carries six fields. A bare one-line task is never enough:
| Field | Content |
|---|---|
| GOAL | humanize the commit or folder so it reads as human-written; this agent owns block N of M |
| ROLE | edit only this block’s files in place; never auto-fix behavior-changing items — surface them |
| SCOPE | in — the exact file list; out — every other path, git history, build output |
| CONTEXT | flow per file already classified, PASS 2 inject ON/OFF, custom instructions verbatim, sibling blocks listed, and the absolute path to the flow rules — never a plugin-root variable, which does not resolve inside a subagent |
| CONSUMER | the skill merges each block’s JSON into one Humanization Report the user acts on |
| DONE | JSON per the mixed.md aggregation schema — stripped, injected, surfaced per file |
Two failure modes the brief prevents: a “helpful” edit outside the block collides with a sibling agent that already owns that file, and a surfaced item quietly fixed never reaches the user who was supposed to decide on it.
Internals
5 flows
| Flow | Domain | Inject stage | Notes |
|---|---|---|---|
| code | source files, comments, docstrings, JavaDoc/JSDoc/KDoc | OFF | formal contract — strip only |
| docs | README, guides, PR/commit, changelogs | ON, restrained | terse for PR/commit |
| social | reddit, forum, slack, discord, chat | ON, casual | burstiness high, fragments OK |
| article | formal essay, published blog, long-form | ON, full | burstiness + real stance |
| mixed | commit / folder dispatcher | per-file routing | routes each file to its flow |
PASS 1 — What gets stripped
| Category | Example | Tier |
|---|---|---|
| Chat scaffolding | ”Certainly!”, “I hope this helps”, “Here’s the rewritten…” | HIGH |
| AI self-attribution | // AI-generated, // Claude suggestion, bot/co-author trailers | HIGH |
| Prompt residue | # Remember to paste..., // Replace with your... placeholder narration | HIGH |
| Unicode normalization | em-dash, smart quotes, arrows — prose and code comments/docstrings only, ASCII form | HIGH |
| Promotional openers | ”In today’s fast-paced world”, “plays a significant role” | HIGH/MED |
| Trivial comment/docstring | // Loop through users, @param userId The user ID | MED density |
| Excess-vocab cluster | delve, leverage, seamless, landscape (co-occurring set) | MED cluster only |
PASS 1 — What gets surfaced (never auto-edited)
Hallucinated package/method/URL refs, fabricated tickets, try/except-everywhere, empty catch-all, placeholder TODO logic, duplicated abstraction layers, happy-path-only tests, CI gaming, unicode inside a string literal or regex, mixed indentation in an indentation-sensitive file. These change meaning — they are reported, not changed.
PASS 1 — What gets kept
WHY comments, useful contracts at any visibility or test location, fixture assumptions,
tool-consumed documentation/doctests, real tickets of any pattern, conditional @throws,
structural banners, algorithm explanations, BDD comments and functional directives.
PASS 2 — Injection weight matrix
| Signal | chat | docs | commit/PR | article | code/API | |
|---|---|---|---|---|---|---|
| Burstiness | high | high | med | low | high | OFF |
| Contractions | high | high | OK | low | high | FORBIDDEN |
| Stance | high | med | none | grounded-why | high | FORBIDDEN |
| Emoji | rare | incidental | no | no | no | no |
| Inject stage | ON | ON | ON | ON terse | ON | OFF |
Block sizing (mixed flow)
| 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 |
The skill cleans surface artifacts and fits register; it does not determine authorship. Weak signals need contextual evidence, and functional preservation takes priority over every cosmetic pattern.
Text Optimize
Trim token waste from prompts and docs. Complements text-human for pre-commit cleanup.
GitHub source
SKILL.md and reference/ flows, preservation rules and language-specific guidance.
Brewtools overview
All brewtools skills — text, secrets, deploy, SSH, provider switching.
Updating plugins
/brewtools:plugin-update to check and update the brewcode plugin suite in one command.
See the FAQ for details.