Humanize Developer Text

Core Principles

1. Delete first, rewrite second. Most AI patterns are padding. Removing them improves the text.
2. Use simple words. Replace "utilize" with "use", "facilitate" with "help", "implement" with "add".
3. Keep sentences short. Break compound sentences. One idea per sentence.
4. Preserve meaning. Never change what the text says, only how it says it.
5. Match the register. Commit messages are terse. READMEs are conversational. API docs are precise.
6. Don't overcorrect. A slightly formal sentence is fine. Only fix patterns that read as obviously AI-generated.

Fix Strategies by Category

Content Patterns

In today's rapidly evolving software landscape, authentication is a crucial
component that plays a pivotal role in securing modern applications.

This guide covers authentication setup for the API.

Vocabulary Patterns

feat: Leverage robust caching paradigm to facilitate seamless data retrieval

feat: add response caching for faster reads

Formatting Patterns

## Error Handling

**Error handling** is a **critical** aspect of building **reliable** applications.
The `handleError` function **catches** and **processes** all **runtime errors**.

## Error Handling

The `handleError` function catches runtime errors and logs them with context.

Communication Patterns

# Great implementation! This elegantly handles the edge case.
# As of my last update, this API endpoint supports JSON.

# Handles the re-entrant edge case from issue #42.
# This endpoint accepts JSON.

Filler Patterns

It's worth noting that the configuration file might potentially need to be
updated. Going forward, this could possibly affect performance.

Update the configuration file. This affects performance.

Code Docs Patterns

def get_user(user_id: int) -> User:
    """Get a user.

    This method retrieves a user from the database by their ID.

    Args:
        user_id: The ID of the user to get.

    Returns:
        User: The user object.

    Raises:
        ValueError: If the user ID is invalid.
    """
    return db.query(User).get(user_id)

def get_user(user_id: int) -> User:
    """Raises UserNotFound if ID doesn't exist in the database."""
    return db.query(User).get(user_id)

Developer Voice Guidelines

• Conversational but precise. Write like you'd explain it to a colleague, but get the details right.
• Direct. State opinions. "Use X" not "You might consider using X".
• Terse where appropriate. Commit messages and code comments should be short. Don't pad them.
• Specific. Replace vague claims with concrete details, numbers, or examples.
• Consistent. Pick one term and stick with it. Don't cycle synonyms.

Register Guide

fix: prevent nil panic in auth middleware

// retry once — transient DNS failures are common in k8s

"""Raises ConnectionError after 3 retries."""

Config file not found at ~/.app/config.yml. Run 'app init' to create one.

Applying Fixes

Safe Fixes (Auto-Apply)

• Delete chat leaks ("Certainly!", "Great question!")
• Delete cutoff disclaimers ("As of my last update")
• Delete filler phrases ("It's worth noting that")
• Delete heading restatements
• Remove emoji from technical docs
• Remove excessive bold formatting
• Swap high-signal AI vocabulary (utilize -> use)
• Delete "As we can see" / "Let's take a look at"
• Delete narrating-obvious comments

Needs Review Fixes (Interactive)

• Rewriting promotional language (may need domain knowledge)
• Fixing synonym cycling (need to pick the right term)
• Rewriting tautological docstrings (need to decide what's actually worth documenting)
• Trimming exhaustive parameter docs (need to decide which params are non-obvious)
• Rewriting commit messages (scope judgment)
• Restructuring formulaic sections (may change document flow)
• Fixing apologetic error messages (wording matters for UX)