Brewtools:Text Human

Text Humanizer

Detect and remove AI-generated artifacts from code and documentation. Process commits, files, or folders with parallel sub-agents.

Language References

Multi-language projects: Load ALL relevant references.

---

Argument

First token = scope (required):

Everything after first token = custom prompt (optional). Free-form text, no quotes needed. Overrides or extends default humanization rules for this run. Passed to every sub-agent prompt.

Custom Prompt Handling

1. Parse: split args into scope (first token) and customPrompt (rest) 2. If customPrompt is present, prepend it to every sub-agent Task prompt as:

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

3. Custom prompt wins over default rules on conflict

---

Architecture

Orchestrator -> Detect Language -> Load Reference -> Analyze -> Classify -> Split (3-10 blocks) -> Parallel Task agents -> Aggregate

Phase 1: Scope Analysis

Commit Mode

Process all text files from commit. No extension filtering: git diff --name-only <hash>^..<hash>

File Inclusion Rules

Path Mode

find <path> -type f \( -name "*.java" -o -name "*.py" -o -name "*.ts" -o -name "*.js" -o -name "*.md" \) | grep -v -E "(target/|node_modules/|\.git/|build/|dist/|__pycache__/)"

Block Count

Single file: process directly without Task delegation.

Phase 2: File Classification

Haiku (Simple)

Sonnet (Complex)

Note: See language-specific references for detailed classification rules.

Phase 3: Block Formation

Group files by type, complexity (avoid mixed haiku/sonnet), line count balance. Keep related files together (same package/directory).

Data files block: YAML, JSON, CSV with comments → haiku for unicode fixes

Phase 4: Parallel Execution

Launch all Task calls in single message for true parallelism.

Task(subagent_type="developer", model="haiku", prompt="> **Context:** BT_PLUGIN_ROOT is available in your context (injected by pre-task.mjs hook).\n\n[CUSTOM_INSTRUCTIONS_IF_ANY]\nBlock 1: [files] [rules] Return JSON")
Task(subagent_type="developer", model="sonnet", prompt="> **Context:** BT_PLUGIN_ROOT is available in your context (injected by pre-task.mjs hook).\n\n[CUSTOM_INSTRUCTIONS_IF_ANY]\nBlock 2: [files] [rules] Return JSON")

If custom prompt was provided, prepend to EVERY sub-agent prompt (after the Context line):

> **Context:** BT_PLUGIN_ROOT is available in your context (injected by pre-task.mjs hook).

CUSTOM INSTRUCTIONS (highest priority, override defaults):
<user's custom prompt text>
---

<output_format> { "files_processed": N, "changes": [{"file": "path", "removed_comments": N, "fixed_unicode": N, "simplified_docs": N}] } </output_format>

Phase 5: Aggregation

Collect JSON results from all agents → merge statistics → generate unified report.

---

<humanization_rules>

AI Artifacts (Universal)

Real vs Fake Issue References

Keep project-specific ticket patterns (INTELDEV-XXXXX, JIRA-XXXXX, GH-XXX). Remove generic AI-invented patterns (BUG-001, FIX-123, ISSUE-42).

Documentation Cleanup (General Principles)

Key Rule: Never convert block docs to inline comments. Delete unnecessary docs entirely; for useful descriptions with trivial params, strip params and keep description.

Comments (Universal)

Keep WHY, remove WHAT.

Formatting (Universal)

</humanization_rules>

---

File Type Rules

YAML/Data Files

Check for unicode in comments. Section comments are valuable.

SQL/XML Comments

Structural comments are valuable. Analyze neighboring files first.

---

Custom Prompt Mode

Custom prompt overrides or extends default rules. Use for:

• Restricting scope: "only remove AI artifacts, don't touch docs"
• Adding rules: "also remove all @author tags"
• Excluding files: "skip test files"
• Style reference: "use style from src/main/Service.java as reference"

Output Format

## Humanization Report

### Execution Summary
| Metric | Value |
|--------|-------|
| Total files | N |
| Blocks | M |
| Haiku/Sonnet | X/Y |

### Block Results
[Per-block tables with file metrics]

### Totals
| Metric | Count |
|--------|-------|
| Files processed | N |
| Comments removed | X |
| Docs simplified | Y |
| Unicode fixed | Z |

Best Practices

• Load language reference first
• Process all commit files (include yaml/data files)
• Check yaml for unicode (comments may have arrows)
• Preserve valuable comments (they add context)
• Skip binaries (avoid corruption)
• Honor style reference if provided
• Keep public API docs
• Group files by complexity
• Launch agents in parallel

Error Handling

Examples

/text-human 3be67487                                              # Commit - all files
/text-human src/main/java/MyService.java                          # Single file
/text-human src/main/java/services/                               # Folder
/text-human 3be67487 don't touch docs on public records           # Commit + custom prompt
/text-human src/ only remove AI artifacts and fix unicode         # Path + custom prompt
/text-human 3be67487 also remove all @author tags                 # Commit + extra rule

Text Humanizer

Detects and removes AI-generated artifacts from code and documentation -- comments like // Added by AI, fake issue numbers, unicode characters, and trivial docs that just restate the function name. Works on commits, files, or folders with parallel sub-agents.

Quick Start

/brewtools:text-human <commit-hash|path> [custom instructions]

Modes

Examples

Good Usage

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

# Humanize a single service class after AI pair-programming
/brewtools:text-human src/main/java/com/example/OrderService.java

# Process an entire package
/brewtools:text-human src/main/java/services/

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

# Only fix unicode and AI markers, leave everything else
/brewtools:text-human src/ only remove AI artifacts and fix unicode

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

Common Mistakes

# Too broad -- will ask you to narrow the scope
/brewtools:text-human entire project

# Running on hand-written code that has no AI artifacts -- wastes time, no changes made
/brewtools:text-human src/legacy/HandCraftedUtils.java

# Pointing at generated/build output -- these files are excluded automatically
/brewtools:text-human target/classes/

What It Changes

What It Keeps

Output

Produces a Humanization Report at the end with:

Files are edited in place. No backup files are created -- use git to revert if needed.

Tips

• Start with a commit hash after an AI-assisted session -- it automatically picks up all changed files including YAML and config that you might forget.
• Use custom instructions to narrow scope: only remove AI artifacts and fix unicode skips the doc cleanup entirely if you want to keep verbose docs.
• Language references are loaded automatically based on file extensions -- Java/Kotlin, TypeScript/JS, and Python each have dedicated cleanup rules.
• Single files skip sub-agent delegation and process directly, so small scopes are fast even without parallelism.

Documentation

Full docs: text-human

Java/Kotlin Reference

Language-specific rules for text-human skill

File Classification

Haiku (Simple)

Sonnet (Complex)

Classification Logic

---

JavaDoc Cleanup

Remove JavaDoc from: private methods, test files, obvious classes. Keep logic description, remove trivial @param/@return.

Logic vs Parameters Rule

NEVER convert JavaDoc `/ /` to inline `//` comment.* Two rules:

1. JavaDoc is unnecessary (private method, obvious class) → DELETE entirely, no replacement 2. JavaDoc has useful description but trivial @param/@return → strip @param/@return, keep description as single-line /** ... */

// BEFORE - useful description + trivial @param/@return:
/**
 * Converts USD to target currency. Returns unchanged if USD.
 * @param amount the amount
 * @param currency the currency
 * @return converted amount
 */

// AFTER - keep description as single-line JavaDoc, strip @param/@return:
/** Converts USD to target currency. Returns unchanged if USD. */
BigDecimal convertCurrency(BigDecimal amount, CurrencyCode currency) { }

// KEEP @param - explains non-obvious behavior:
/**
 * @param hasExtraStops true=include ALL loads, false/null=only WITHOUT extra stops
 */

Private Methods

// REMOVE - private methods don't need JavaDoc:
/** Validates the filter. */
private boolean isValidFilter(Filter f) { }

/** Builds full condition. */
private Condition buildFullCondition() { }

/** Rounds value to scale. @param value the value @param scale the scale */
private Double roundToScale(double value, int scale) { }

Obvious DTOs/Entities

// REMOVE - class name is self-explanatory:
/** Filter DTO for rates history queries. */
@Value @Builder
public class RatesHistoryFilter { }

/** Entity for rate history data. */
@Value @Builder
public class HistoryRateEntity { }

// KEEP - adds non-obvious context:
/** Cached for 1 hour. Thread-safe via copy-on-write. */
public class CompanyCache { }

Test Files

Remove all JavaDoc from: test classes (*Test.java, *Spec.kt), test helpers (*Data.java, *Requests.java, *Fixtures.java), any file in src/test/.

// REMOVE - test class:
/** Test class for LoadsHistoryRepository. */
class LoadsHistoryRepositoryTest {
    /** Tests filtering by company ID. */
    @Test void testFilterByCompanyId() { }
}

// REMOVE - test helper classes:
/** Expected data for rates stats tests. */
@UtilityClass
public class RatesStatsExpectedData {
    /** Factory method for expected stats. */
    public static Stats expected() { }
}

// CORRECT - no JavaDoc, clear method names:
class LoadsHistoryRepositoryTest {
    @Test
    @DisplayName("Should filter loads by company ID")
    void filterByCompanyId() {
        // GIVEN
        // WHEN
        // THEN
    }
}

@UtilityClass
public class RatesStatsExpectedData {
    public static Stats expected() { }
}

---

Comments

Preserve all BDD comments: // GIVEN, // WHEN, // THEN, // AND

---

Issue References

// REMOVE - AI-invented numbers:
// BUG-001 fix: ...
// FIX-123: ...
// ISSUE-42: ...

// KEEP - real ClickUp/Jira tickets:
// INTELDEV-19207: ...
// Workaround for JIRA-12345

Keep project-specific ticket patterns (INTELDEV-XXXXX, JIRA-XXXXX). Remove generic patterns (BUG-001, FIX-123).

---

Pre-Completion Checklist

Scan Pattern

# Semantic search queries for grepai_search:
grepai_search("private methods with javadoc")
grepai_search("trivial param documentation")
grepai_search("test helper classes")
grepai_search("DTO classes with javadoc")

# Fallback grep patterns:
grep -n "^\s*/\*\*" <file>           // Find all JavaDoc
grep -n "private.*{" <file>          // Find private methods

Files to Double-Check

Repository classes (private helper methods), Service classes (internal methods), Test helper classes (not ending in Test), DTOs/Entities (redundant class-level JavaDoc).

---

File Inclusion

Python Reference

Language-specific rules for text-human skill

File Classification

Haiku (Simple)

Sonnet (Complex)

Classification Logic

---

Docstring Cleanup

Remove docstrings from: private methods, test files, obvious functions. Keep public API docs.

Docstring Styles

Handle all common styles (Google, NumPy, Sphinx):

# REMOVE - trivial Google style:
def get_user(user_id: int) -> User:
    """Get user by ID.

    Args:
        user_id: The user ID.

    Returns:
        The user object.
    """

# CORRECT - no docstring needed:
def get_user(user_id: int) -> User:
    ...

# KEEP - adds context:
def get_user(user_id: int) -> User:
    """Fetches from cache first, falls back to DB. Returns None if not found."""

Private Methods

# REMOVE - private methods don't need docstrings:
def _validate_input(self, data: dict) -> bool:
    """Validate the input data."""

def __calculate_hash(self, value: str) -> int:
    """Calculate hash for value."""

# CORRECT - no docstrings:
def _validate_input(self, data: dict) -> bool:
    ...

def __calculate_hash(self, value: str) -> int:
    ...

Classes

# REMOVE - obvious class:
class UserRepository:
    """Repository for user operations."""

class OrderService:
    """Service for order management."""

# CORRECT - no docstring:
class UserRepository:
    ...

# KEEP - non-obvious behavior:
class RateLimiter:
    """Token bucket algorithm. Thread-safe. Tokens refill every 100ms."""

Dunder Methods

# REMOVE - dunder methods are well-known:
def __init__(self, name: str):
    """Initialize with name."""

def __str__(self) -> str:
    """Return string representation."""

def __len__(self) -> int:
    """Return length."""

# CORRECT - no docstrings on dunders:
def __init__(self, name: str):
    self.name = name

# EXCEPTION - keep if non-standard behavior:
def __eq__(self, other) -> bool:
    """Compares by ID only, ignores other fields."""

---

Comments

Type Comments

# REMOVE - use type hints instead:
x = []  # type: List[int]
y = None  # type: Optional[str]

# CORRECT - inline type hints:
x: list[int] = []
y: str | None = None

# KEEP - when type hints not possible:
# type: ignore[arg-type]  # mypy false positive

Noqa Comments

---

Test Files

Remove all docstrings from: test files, fixtures, conftest.py.

# REMOVE - test file:
class TestUserService:
    """Tests for UserService."""

    def test_create_user(self):
        """Test creating a user."""

# CORRECT - no docstrings:
class TestUserService:
    def test_create_user(self):
        # Arrange
        # Act
        # Assert
        ...

# REMOVE - fixtures:
@pytest.fixture
def mock_user():
    """Create mock user for tests."""

# CORRECT:
@pytest.fixture
def mock_user():
    ...

---

Pre-Completion Checklist

Scan Pattern

# Semantic search:
grepai_search("private methods with docstrings")
grepai_search("trivial docstring parameters")
grepai_search("test file documentation")

# Fallback grep:
grep -n '"""' <file>              # Find docstrings
grep -n "def _" <file>            # Find private methods

---

File Inclusion

TypeScript/JavaScript/React Reference

Language-specific rules for text-human skill

File Classification

Haiku (Simple)

Sonnet (Complex)

Classification Logic

---

JSDoc Cleanup

Remove JSDoc from: private functions, test files, obvious components. Keep public API docs.

JSDoc vs TypeScript

Prefer TypeScript types over JSDoc when both exist:

// REMOVE - redundant JSDoc with TS types:
/**
 * @param {string} name - The user name
 * @param {number} age - The user age
 * @returns {User} The created user
 */
function createUser(name: string, age: number): User { }

// KEEP - only TS types:
function createUser(name: string, age: number): User { }

// KEEP - adds context beyond types:
/** Creates user and sends welcome email. Throws if email fails. */
function createUser(name: string, age: number): User { }

React Components

// REMOVE - obvious component:
/** Button component that renders a button. */
const Button: FC<ButtonProps> = ({ onClick, children }) => { }

/** User profile card component. */
const UserCard: FC<UserCardProps> = ({ user }) => { }

// KEEP - non-obvious behavior:
/** Debounces input by 300ms. Calls onChange only after user stops typing. */
const DebouncedInput: FC<InputProps> = ({ onChange }) => { }

// KEEP - complex props explanation:
/**
 * @param renderItem - Custom renderer, receives (item, index, isLast)
 * @param onEndReached - Called when scroll reaches 80% of list
 */
const VirtualList: FC<ListProps> = ({ renderItem, onEndReached }) => { }

Hooks

// REMOVE - obvious hook:
/** Hook that manages loading state. */
const useLoading = () => { }

/** Hook for user data. */
const useUser = (id: string) => { }

// KEEP - non-obvious behavior:
/** Fetches on mount + refetches every 30s. Pauses when tab inactive. */
const usePolling = (url: string, interval = 30000) => { }

/** Returns memoized callback. Deps auto-tracked via proxy. */
const useAutoCallback = <T extends Function>(fn: T): T => { }

---

Comments

ESLint/TSLint Comments

Preserve

• // @ts-expect-error with explanation
• // @ts-ignore (but prefer @ts-expect-error)
• Region comments // #region, // #endregion

---

Test Files

Remove all JSDoc from: test files, test utilities, mocks, fixtures.

// REMOVE - test file:
/** Tests for UserService. */
describe('UserService', () => {
  /** Should create user with valid data. */
  it('creates user', () => { })
})

// CORRECT - no JSDoc, clear descriptions:
describe('UserService', () => {
  it('creates user with valid data', () => {
    // Arrange
    // Act
    // Assert
  })
})

// REMOVE - test utilities:
/** Creates mock user for tests. */
export const createMockUser = () => { }

// CORRECT:
export const createMockUser = () => { }

---

Pre-Completion Checklist

Scan Pattern

# Semantic search:
grepai_search("jsdoc on private functions")
grepai_search("redundant type annotations")
grepai_search("test file documentation")

# Fallback grep:
grep -n "/\*\*" <file>              // Find JSDoc
grep -n "^const.*=" <file>         // Find functions

---

File Inclusion