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

FieldValue
Command/brewtools:text-human
Arguments[prompt] [path|commit|folder|text] [custom instructions]
Modelsonnet (haiku for simple blocks in mixed flow)
Contextsession
ToolsRead, Write, Edit, Grep, Glob, Bash, Agent, AskUserQuestion

When to use

SituationCommand
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

  1. 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).

  2. 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 AskUserQuestion as fallback. The custom prompt both selects/overrides the flow and adds custom rules at highest priority.

  3. Clean-tree precondition

    Before the first edit on any writing flow, the skill runs git status —porcelain over the resolved target paths only — there is no backup, so git is the only undo. Clean → proceeds. Dirty → one AskUserQuestion listing 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.

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

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

  6. 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 Agent calls 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.

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

FieldContent
GOALhumanize the commit or folder so it reads as human-written; this agent owns block N of M
ROLEedit only this block’s files in place; never auto-fix behavior-changing items — surface them
SCOPEin — the exact file list; out — every other path, git history, build output
CONTEXTflow 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
CONSUMERthe skill merges each block’s JSON into one Humanization Report the user acts on
DONEJSON 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

FlowDomainInject stageNotes
codesource files, comments, docstrings, JavaDoc/JSDoc/KDocOFFformal contract — strip only
docsREADME, guides, PR/commit, changelogsON, restrainedterse for PR/commit
socialreddit, forum, slack, discord, chatON, casualburstiness high, fragments OK
articleformal essay, published blog, long-formON, fullburstiness + real stance
mixedcommit / folder dispatcherper-file routingroutes each file to its flow

PASS 1 — What gets stripped

CategoryExampleTier
Chat scaffolding”Certainly!”, “I hope this helps”, “Here’s the rewritten…”HIGH
AI self-attribution// AI-generated, // Claude suggestion, bot/co-author trailersHIGH
Prompt residue# Remember to paste..., // Replace with your... placeholder narrationHIGH
Unicode normalizationem-dash, smart quotes, arrows — prose and code comments/docstrings only, ASCII formHIGH
Promotional openers”In today’s fast-paced world”, “plays a significant role”HIGH/MED
Trivial comment/docstring// Loop through users, @param userId The user IDMED density
Excess-vocab clusterdelve, 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

Signalredditchatdocscommit/PRarticlecode/API
BurstinesshighhighmedlowhighOFF
ContractionshighhighOKlowhighFORBIDDEN
Stancehighmednonegrounded-whyhighFORBIDDEN
Emojirareincidentalnononono
Inject stageONONONON terseONOFF

Block sizing (mixed flow)

FilesLinesBlocksAgents
1-2<2001direct
3-5<5003parallel
6-10500-15005parallel
11-201500-30007parallel
21+3000+10parallel

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

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