git:20260930.2f50853 to git:20261012.dd21170

53 added, 94 removed. Audit A to A.

---

name: text-human

description: "Humanizes code, docs, articles, reddit/chat, javadoc -- strips AI artifacts, fixes unicode, fits register. Triggers: humanize, ai artifacts, unicode fix, article, reddit, javadoc."

user-invocable: true

disable-model-invocation: true

argument-hint: "[prompt] [path|commit|folder|text] [custom instructions]"

allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, Agent, AskUserQuestion]

model: sonnet

---

# Text Humanizer

- Humanizes source/comments/docstrings, technical docs, commits/PRs, articles and reddit/chat.

- Choose ONE flow, lazy-load its rules/relevant pattern sections, STRIP validated AI tells then

- gated INJECT domain style. Removes surface artifacts/fits register; never claims authorship detection.

+ Humanizes source code and docstrings, technical docs, commits/PRs, articles and reddit/chat: strips

+ validated AI tells, then injects domain style where the flow allows. Never claims to detect AI

+ authorship.

## Prompt contract

- Position 1 of `$ARGUMENTS` is a **free-form prompt** (RU/EN) -- modes ("flows") and flags are

- optional and may follow in any order. Nobody types keys: resolve the flow + scope FROM the

- prompt. Phase 0 below IS this skill's resolution algorithm (explicit keyword -> path/extension

- -> content sniff); the Flow table there carries EN/RU keywords and `Mutates?` per flow.

+ `$ARGUMENTS` is one free-form RU/EN prompt; flow keywords may sit anywhere in it. There are no mode

+ flags: Phase 0 below is this skill's resolution algorithm, and its Flow table carries the EN/RU

+ keywords and `Mutates?` per flow.

- 1. Strip nothing -- there are no mode flags, only the flow keywords in the table below.

- 2. Explicit intent keyword (table below) wins outright, no scoring; unresolved cases fall

- through Phase 0's own priority order (keyword -> extension -> content sniff).

- 3. Empty arguments -> no assumed flow: Phase 0 Step 4's existing `AskUserQuestion` ("What to

- humanize?") is the ONE scoping question this contract requires -- do not skip it and do not

- guess a flow.

- 4. Outcome-changing ambiguity beyond the flow itself -> ONE `AskUserQuestion` BEFORE any work.

- Phase 0.5's dirty-path gate IS that question whenever it fires, and it outranks the scoping one.

- 5. Prose that is not a flow keyword is still input: `customPrompt` (Phase 0 Argument parsing)

+ 1. Flow: an explicit intent keyword (table below) wins outright, no scoring; unresolved cases fall

+ through Phase 0's own priority order (keyword -> path/extension -> content sniff). Empty -> no

+ assumed flow: Phase 0 Step 4's `AskUserQuestion` ("What to humanize?") is the ONE scoping

+ question -- do not skip it and do not guess a flow.

+ 2. Scope: prose that is not a flow keyword is still input: `customPrompt` (Phase 0 Argument parsing)

extracts it and both selects/overrides the flow and adds custom rules.

+ 3. Ask: outcome-changing ambiguity beyond the flow itself -> ONE `AskUserQuestion` before any work.

+ Phase 0.5's dirty-path gate IS that question whenever it fires, and it outranks the scoping one.

- Then print this block ONCE, before the first action:

+ Print once, right after Phase 0 announces `Flow: <name> -- <reason>`, before Phase 1 touches any

+ file; SCOPE names the resolved target paths -- for `mixed`, the resolved block list (labels and plan

+ values English, INPUT verbatim):

```

PLAN — brewtools:text-human

INPUT: <arguments verbatim, or "(empty)">

MODE: <resolved flow> — <explicit | matched keyword: X | content-sniff | AskUserQuestion>

SCOPE: <resolved target paths (file/commit/folder/text), custom instructions if any>

DO: <2-5 imperative bullets>

RESULT: <what the user ends up holding>

```

- Labels/plan values are English; INPUT remains verbatim. Print right after Phase 0

- announces `Flow: <name> -- <reason>`, before Phase 1 touches any file. SCOPE names the resolved

- target paths -- for `mixed`, the resolved block list.

- ## Two-pass model (applies to every flow)

- - PASS 1 -- STRIP: remove validated AI tells per `@reference/ai-patterns.md`. Only HIGH-tier universal-strip acts on single instances. MED density-signals act ONLY when several co-occur. Behavior-changing items (hallucinated refs, fake tickets, try/except-everything) are SURFACED for review, never auto-edited.

- - PASS 2 -- INJECT (gated): apply `@reference/human-patterns.md` for the flow's domain. HARD-OFF for code / API / formal-contract. GLOBAL GUARD: never inject typos, errors, or fabricated references in any flow.

- ## Phase 0 -- Greedy flow detection (do this FIRST)

- Before any processing, parse the argument, pick exactly ONE flow, and ANNOUNCE it:

+ ## Two-pass model

- `Flow: <name> -- <one-line why>`

+ - PASS 1 STRIP per `@reference/ai-patterns.md`: HIGH tier acts on one instance, MED only on a cluster. Behavior-changing items (hallucinated refs, fake tickets, try/except-everything) change meaning when edited: surface them, never edit.

+ - PASS 2 INJECT per `@reference/human-patterns.md`, gated by domain: off for code, API docs, formal contracts. No flow injects typos, errors or fabricated references.

- Then greedy-load ONLY the chosen flow file plus the pattern sections it needs (lazy -- not everything).

+ ## Phase 0 -- Greedy flow detection

- ### Argument parsing (universal)

- Accept all of: path, commit hash, folder, free-text prompt, path+prompt, no args.

+ Pick exactly one flow, announce `Flow: <name> -- <reason>`, then load only its flow file and the

+ pattern sections that file names.

- 1. Take the first token. If it resolves to an existing path OR matches a 7+ hex git hash -> that is `scope`, the rest is `customPrompt`.

- 2. Otherwise the WHOLE input is a `customPrompt` (the text to humanize may be inline, or it may describe intent). Flow is detected from the prompt + any inline content.

- 3. `customPrompt` both selects/overrides the flow AND adds custom rules (highest priority on conflict).

- 4. No args at all -> AskUserQuestion fallback is allowed ONLY here ("What to humanize?" -> commit / file / folder / paste text). Prefer inferring whenever possible.

+ ### Argument parsing

+ 1. First token resolves to an existing path or matches a 7+ hex git hash -> `scope`; the rest is `customPrompt`.

+ 2. Otherwise the whole input is `customPrompt` (inline text or intent); detect the flow from it.

+ 3. `customPrompt` rules win over flow defaults on conflict.

+ 4. No args -> the only allowed `AskUserQuestion` here: "What to humanize?" (commit / file / folder / paste text).

### Detection signals (priority order)

- 1. Explicit intent keywords in the prompt (RU+EN):

- - reddit / forum / slack / discord / chat / чат / форум -> social

- - javadoc / jsdoc / kdoc / docstring / "api doc" / апи док -> code (CLEAN-ONLY sub-profile)

- - pr / pull request / commit / changelog / readme / docs / guide / коммит / документация -> docs

- - article / blog / essay / post / статья / эссе -> article

- - commit hash, or folder of mixed files -> mixed

- 2. Path / extension:

- - `.java/.kt/.py/.ts/.tsx/.js/.jsx/.go/.rs/.cpp/...` -> code

- - `.md/.mdx/.rst` -> docs; sniff content: long-form essay/blog -> article

- - 7+ hex git hash -> mixed

- - folder -> mixed

- 3. Content sniff:

- - short fragmented lines / no caps -> social

- - structured prose paragraphs with a thesis -> article

- - imperative + code blocks -> docs

+ 1. Intent keyword from the Flow table below; javadoc/jsdoc/kdoc/docstring/"api doc" select code's CLEAN-ONLY sub-profile.

+ 2. Path: code extension -> code; `.md/.mdx/.rst` -> docs (long-form essay/blog content -> article); 7+ hex git hash or folder -> mixed.

+ 3. Content sniff: short fragmented lines / no caps -> social; prose paragraphs with a thesis -> article; imperative + code blocks -> docs.

### Flow -> file

|------|-------------|-------------|----------|------|--------|

- Pattern files (load the sections the flow needs): `@reference/ai-patterns.md`, `@reference/human-patterns.md`.

## Phase 0.5 -- Clean-tree precondition (every flow that writes)

- This skill rewrites files in place and keeps no backup, so git IS the undo. Before the first edit,

- over the resolved target paths only:

+ Files are rewritten in place with no backup; git is the only undo. Before the first edit, over the

+ resolved target paths only:

```bash

- git status --porcelain -- <resolved paths>

+ git status --porcelain -- "<resolved path>" # one quoted arg per target path

```

- Empty -> proceed.

- - Non-empty -> use existing explicit authorization for those named dirty edits, else ONE

- `AskUserQuestion` listing paths: proceed on them / process only the

- clean ones / abort. This is the skill's single clarifying question -- it replaces, not adds to,

- the Phase 0 scoping question, and `mixed`'s commit-mode check is this same gate scoped to the

- commit's paths.

- - Not a git repo (`git rev-parse --git-dir` fails) -> say so and require an explicit go-ahead;

- there is nothing to revert to.

+ - Non-empty, edits on those paths not already authorized -> ONE `AskUserQuestion` listing them:

+ proceed on them / process only the clean ones / abort. It replaces the Phase 0 scoping question;

+ `mixed` commit mode runs this gate over the commit's paths.

+ - Not a git repo (`git rev-parse --git-dir` fails) -> say so; proceed only on an explicit go-ahead.

- Inline text and other non-file input skip this -- nothing on disk changes.

+ Inline text skips this gate.

## Phase 1 -- Execute the flow

- - Single file or inline text -> apply the chosen flow's rules directly, no Agent delegation.

- - mixed (commit / folder) -> follow `@reference/flows/mixed.md`: block split, haiku/sonnet classification, parallel Agent launch, JSON aggregation. Each file is routed to its correct flow's rules.

+ - Single file or inline text -> apply the flow's rules directly, no delegation.

+ - mixed (commit / folder) -> follow `@reference/flows/mixed.md`; each file gets its own flow's rules. Delegates cannot resolve relative paths: name rule files under `${CLAUDE_SKILL_DIR}/reference/`.

- Custom prompt, when present, is prepended to direct processing and to every sub-agent Agent prompt:

+ A custom prompt is prepended to direct processing and every delegate prompt:

```

CUSTOM INSTRUCTIONS (highest priority, override defaults):

---

```

### Delegation (mixed flow)

- Main owns every spawn/acceptance; delegates never nest and return decisions to main. One SA =

- ONE block/~<=5 files/~<=10 steps. Large commit/folder MUST split into N blocks, spawned in ONE message.

- Every spawn prompt MUST carry:

- | Field | Content |

- |-------|---------|

- | GOAL | overall task/purpose beyond editing |

- | ROLE | owned responsibility + forbidden changes |

- | SCOPE | exact paths/commands in/out of bounds |

- | CONTEXT | prior work/owners, parallel work; relevant to this agent only |

- | CONSUMER | next consumer + required result shape |

- | DONE | acceptance criteria + exact return format |

+ Main owns every spawn and acceptance; delegates never nest and return open decisions. One

+ delegate = one block (~<=5 files, ~<=10 steps); a large commit or folder splits into N blocks spawned in one message.

+ Every spawn brief carries six labeled fields, since a subagent starts with an empty context: GOAL (task + why), ROLE (owns, must not touch), SCOPE (paths/commands in and out), CONTEXT (done, by whom, in parallel), CONSUMER (who uses the result + its shape), DONE (acceptance + return: verdict first, evidence, bounded; long output to a file, path returned).

A bare one-line task is never enough. Shape:

```

Agent(subagent_type="general-purpose", prompt="

GOAL: humanizing <commit|folder> so it reads as human-written; you own block <N>/<M>,

siblings own the rest and the reports are merged into one Humanization Report.

ROLE: edit only your block's files in place. Do NOT touch files outside the block,

do NOT auto-fix behavior-changing items — surface them instead.

SCOPE: in — <exact file list>. Out — every other path, git history, build output.

CONTEXT: classification is already done — flow=<code|docs|social|article> per file, PASS 2

inject <ON|OFF> for this domain, custom instructions (verbatim, highest priority) if any.

Sibling agents hold blocks <list> of the same commit; every file outside your list is

already claimed, so a "helpful" extra edit collides with another agent.

CONSUMER: the skill merges each block's JSON into one Humanization Report; the user acts on

'surfaced' items by hand, so a surfaced item you silently fixed never reaches them.

DONE: JSON per the mixed.md aggregation schema — stripped, injected, surfaced per file.

Surfaced items are listed, never applied.

```

## Output -- Humanization Report

```

## Humanization Report

Flow: <name>

### Summary

| Metric | Value |

|--------|-------|

| Files / blocks | N / M |

| Haiku / Sonnet | X / Y |

### Results

[per-file or per-block: stripped, injected, surfaced]

### Surfaced for review (NOT auto-applied)

[file:line -- issue] e.g. hallucinated ref, fabricated ticket, try/except-everything

### Totals

| Metric | Count |

|--------|-------|

| AI tells stripped | X |

| Human edits injected | Y |

| Items surfaced | Z |

| Unicode normalized | W |

```

- Files are edited in place. No backups -- git is the only undo, which is why Phase 0.5 refuses to

- start over dirty paths without an explicit answer.

## Error handling

| Error | Action |

|-------|--------|

| Agent failure/partial output | Keep completed edits/evidence, report incomplete block, continue others; never count unverified work done |

- | File read error | Skip, note in report |

- | Binary file | Skip, note in report |

+ | File read error, binary file | Skip, note in report |

| No changes | Report "No humanization required" |

## Examples

```bash

- /text-human src/main/java/OrderService.java # code flow, single file

- /text-human 3be67487 # mixed flow, commit

- /text-human src/main/java/services/ # mixed flow, folder

- /text-human review this reddit reply: "<text>" # social flow, inline text

- /text-human humanize this blog post: "<text>" # article flow

- /text-human clean the javadoc in PaymentApi.java # code flow, CLEAN-ONLY

- /text-human 3be67487 also drop all @author tags # mixed + custom rule

- /text-human src/ only strip AI artifacts, no inject # custom prompt overrides

+ /brewtools:text-human src/main/java/OrderService.java # code flow, single file

+ /brewtools:text-human 3be67487 # mixed flow, commit

+ /brewtools:text-human src/main/java/services/ # mixed flow, folder

+ /brewtools:text-human review this reddit reply: "<text>" # social flow, inline text

+ /brewtools:text-human humanize this blog post: "<text>" # article flow

+ /brewtools:text-human clean the javadoc in PaymentApi.java # code flow, CLEAN-ONLY

+ /brewtools:text-human 3be67487 also drop all @author tags # mixed + custom rule

+ /brewtools:text-human src/ only strip AI artifacts, no inject # custom prompt overrides

```