Humanize Developer Text

Fix AI-generated writing patterns in docs, docstrings, commit messages, PR descriptions, and code comments. Prioritize deletion over rewriting — the best fix for filler is removal.

Core Principles

• Delete first, rewrite second. Most AI patterns are padding. Removing them improves the text.

• Use simple words. Replace "utilize" with "use", "facilitate" with "help", "implement" with "add".

• Keep sentences short. Break compound sentences. One idea per sentence.

• Preserve meaning. Never change what the text says, only how it says it.

• Match the register. Commit messages are terse. READMEs are conversational. API docs are precise.

• Don't overcorrect. A slightly formal sentence is fine. Only fix patterns that read as obviously AI-generated.

Fix Strategies by Category

Content Patterns

Type Strategy Risk

Promotional language Replace superlatives with specifics Needs review

Vague authority Delete the claim or add a citation Safe

Formulaic structure Remove the intro/conclusion wrapper Needs review

Synthetic openers Delete the opener, start with the point Safe

Before:

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

After:

This guide covers authentication setup for the API.

Vocabulary Patterns

Type Strategy Risk

High-signal AI words Direct word swap Safe

Low-signal clusters Reduce density, keep 1-2 Needs review

Copula avoidance Use "is/are" naturally Safe

Rhetorical devices Delete the question, state the fact Safe

Synonym cycling Pick one term, use it consistently Needs review

Commit inflation Rewrite to match actual change scope Needs review

Word swap reference:

AI Word Replacement

utilize use

leverage (as "use") use

delve look at, explore, examine

facilitate help, enable, let

endeavor try, work, effort

harnessing using

paradigm approach, model, pattern

whilst while

furthermore also, and

moreover also, and

robust (non-technical) reliable, solid, strong

seamless smooth, easy

cutting-edge modern, latest, new

pivotal important, key

elevate improve

empower let, enable

revolutionize change, improve

unleash release, enable

synergy (delete — rarely means anything)

embark start, begin

Before:

feat: Leverage robust caching paradigm to facilitate seamless data retrieval

After:

feat: add response caching for faster reads

Formatting Patterns

Type Strategy Risk

Boldface overuse Remove bold from non-key terms Safe

Emoji decoration Remove emoji from technical content Safe

Heading restatement Delete the restating sentence Safe

Before:

Error Handling

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

After:

Error Handling

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

Communication Patterns

Type Strategy Risk

Chat leaks Delete entirely Safe

Cutoff disclaimers Delete entirely Safe

Sycophantic tone Delete or neutralize Safe

Apologetic errors Rewrite as direct error message Needs review

Before:

Great implementation! This elegantly handles the edge case.

As of my last update, this API endpoint supports JSON.

After:

Handles the re-entrant edge case from issue #42.

This endpoint accepts JSON.

Filler Patterns

Type Strategy Risk

Filler phrases Delete the phrase Safe

Excessive hedging Remove qualifiers, state directly Safe

Generic conclusions Delete the conclusion paragraph Safe

Before:

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

After:

Update the configuration file. This affects performance.

Code Docs Patterns

Type Strategy Risk

Tautological docstrings Delete or add real information Needs review

Narrating obvious code Delete the comment Safe

"This noun verbs" Rewrite in active/direct voice Safe

Exhaustive enumeration Keep only non-obvious params Needs review

Before:

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)

After:

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

Good developer writing is:

• 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

Artifact Tone Length Example

Commit message Terse, imperative 50-72 chars fix: prevent nil panic in auth middleware

Code comment Brief, explains why 1-2 lines // retry once — transient DNS failures are common in k8s

Docstring Precise, adds value What the name doesn't tell you """Raises ConnectionError after 3 retries."""

PR description Structured, factual Context + what changed + how to test Bullet points, not paragraphs

README Conversational, scannable As short as possible Start with what it does, then how to use it

Error message Actionable, specific What happened + what to do Config file not found at ~/.app/config.yml. Run 'app init' to create one.

Applying Fixes

Safe Fixes (Auto-Apply)

These are mechanical and can be applied without human review:

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

These require a human to verify the replacement preserves intent:

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