Humanize text

Edit the supplied text or repository artifact in place only when authorized. Preserve technical meaning, identifiers, citations, and house style while removing repetitive phrasing, filler, and synthetic narration. Return a focused diff and do not delegate unless explicitly requested.

Complete native workflow

Follow every phase below. When a phase delegates work, use Codex collaboration with only task_name and message; treat each "Codex delegation brief" block as role and message content, not executable syntax. Required approval: main presents a concrete, reviewable proposal in chat and waits for an actual user reply before dependent action. Existing authorization for the same scope remains valid; do not ask again. Optional clarification: use request_user_input_async only if exposed, or request_user_input only if available in the current runtime/mode, for optional choices and never approval. Otherwise ask in main chat. Delegated agents return unresolved questions to main. Silence, elapsed time and tool errors are not approval. Resolve <skill-directory>, <plugin-root>, <project-root>, and <arguments> before running commands.

Text Humanizer

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

<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. 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 main-chat user gate ("What to humanize?") is the ONE scoping question -- do not skip it and do not guess a flow. Unanswered or headless -> stop, "nothing to humanize", no edits.
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. Invoked implicitly mid-task, the invocation text is the prompt: the path, commit hash or exact text, never a summary of it.
3. Ask: outcome-changing ambiguity beyond the flow itself -> ONE main-chat user gate before any work. Phase 0.5's dirty-path gate IS that question whenever it fires, and it outranks the scoping one. Unanswered or headless -> its safest option (Phase 0.5); nothing blocks.

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 | main-chat user gate>
SCOPE:  <resolved target paths (file/commit/folder/text), custom instructions if any>
DO:     <2-5 imperative bullets>
RESULT: <what the user ends up holding>

Two-pass model

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

Phase 0 -- Greedy flow detection

Pick exactly one flow, announce Flow: <name> -- <reason>, then load only its flow file and the pattern sections that file names.

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 main-chat user gate here: "What to humanize?" (commit / file / folder / paste text).

Detection signals (priority order)

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

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

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

git status --porcelain -- '<resolved path>'

One single-quoted arg per target path.

• Empty -> proceed.
• Non-empty, edits on those paths not already authorized -> ONE main-chat user gate 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. Unanswered -> only the clean ones; none clean -> stop, no edits.
• Not a git repo (git rev-parse --git-dir fails) -> say so; proceed only on an explicit go-ahead (unanswered -> stop, no edits).

Inline text skips this gate.

Phase 1 -- Execute the flow

• 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 <skill-directory>/reference/.

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

CUSTOM INSTRUCTIONS (highest priority, override defaults):
<customPrompt>
---

Delegation (mixed flow)

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:

spawn_agent({"task_name":"general_purpose_1","message":"Assigned role: general-purpose. The main session supplies matching native role instructions when available; report a role gap rather than claiming a custom type was instantiated. Perform this bounded work only; do not spawn or delegate children.\n\nGOAL: humanizing <commit|folder> so it reads as human-written; you own block <N>/<M>,\n  siblings own the rest and the reports are merged into one Humanization Report.\nROLE: edit only your block's files in place. Do NOT touch files outside the block,\n  do NOT auto-fix behavior-changing items — surface them instead.\nSCOPE: in — <exact file list>. Out — every other path, git history, build output.\nCONTEXT: classification is already done — flow=<code|docs|social|article> per file, PASS 2\n  inject <ON|OFF> for this domain, custom instructions (verbatim, highest priority) if any.\n  Sibling agents hold blocks <list> of the same commit; every file outside your list is\n  already claimed, so a \"helpful\" extra edit collides with another agent.\nCONSUMER: the skill merges each block's JSON into one Humanization Report; the user acts on\n  'surfaced' items by hand, so a surfaced item you silently fixed never reaches them.\nDONE: JSON per the mixed.md aggregation schema — stripped, injected, surfaced per file.\n  Surfaced items are listed, never applied.\n"})

Output -- Humanization Report

## Humanization Report

Flow: <name>

### Summary
| Metric | Value |
|--------|-------|
| Scope | <file|commit|folder|text> |
| Files / blocks | N / M |
| fast model / balanced model | 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 |

Error handling

Examples

$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