Brewcode: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:** BC_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:** BC_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:** BC_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

Remove AI artifacts and simplify documentation from your code.

What It Does

Cleans up code and documentation by removing AI-generated comments, simplifying excessive docs, and fixing unicode characters. Works with individual files, folders, or entire commits.

How to Use

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

Examples

# Process a specific commit
/brewcode:text-human 3be67487

# Process a single file
/brewcode:text-human src/main/java/MyService.java

# Process a folder
/brewcode:text-human src/main/java/services/

# With custom instructions
/brewcode:text-human src/ only remove AI artifacts, don't touch docs

What Gets Removed

• AI-generated comments: // Added by AI, // Claude suggestion
• Fake issue numbers: BUG-001, FIX-123
• Unicode artifacts: smart quotes, arrows, dashes
• Trivial documentation that just restates the function name
• Excessive comments that describe obvious code

What Gets Kept

• Real issue references (your project's ticket patterns)
• "Why" comments explaining non-obvious behavior
• Public API documentation
• Structural comments in SQL/YAML files

Speed

Uses parallel processing for large codebases. Simple files processed with Haiku model, complex code with Sonnet for faster results.

Languages Supported

Java, Kotlin, TypeScript, JavaScript, Python, SQL, YAML, Markdown, and more.

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