# How Humanizer's Two-Pass Rewrite Process Works: Draft, Check, and Finalize

> Discover how Humanizer's two-pass rewrite process transforms AI text. Learn about drafting, checking, and finalizing for a natural, human-like output.

- Repository: [Siqi Chen/humanizer](https://github.com/blader/humanizer)
- Tags: deep-dive
- Published: 2026-09-07

---

**Humanizer rewrites AI-generated text in two sequential passes—first creating a draft that removes structural "tells," then verifying and polishing for a final, human-like output.**

The **two-pass rewrite process** is the core mechanism behind `blader/humanizer`, a skill designed to strip AI-sounding patterns from machine-generated prose. Each pass has a distinct purpose: the first handles structural cleanup, while the second ensures accuracy and stylistic refinement. This separation reduces the risk of hallucinations and missed artifacts.

## Pass One: Draft the Rewrite

The **first pass** scans the input and **marks every "tell"**—those recognizable AI-style patterns that give away machine authorship. These tells are defined in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) and include structural giveaways like repetitive transitions, hedging language, and formulaic conclusions.

After identification, Humanizer produces a **draft rewrite**. This draft preserves every factual claim, name, date, and citation while removing or reshaping the identified tells. However, it may still carry subtle AI-like phrasing because the focus is structural, not stylistic polish.

According to the source in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) (lines 35-38), this pass is intentionally "good enough" rather than perfect—its job is fact-preserving transformation, not final voice matching.

## Pass Two: Check and Finalize

The **second pass** serves dual purposes: **verification and refinement**.

1. **Verification** – Humanizer checks the draft against the same tell patterns, confirming no new facts have been introduced and no original claims have been lost. This step catches hallucinations before they reach the user.

2. **Voice matching** – The pass applies rhythm, punctuation, and stylistic preferences from any provided sample. It also removes any remaining "weak-alone" tells that survived the first pass.

The result is the **final version** returned to the user.

## Why Two Passes Beat One

The draft-and-final architecture solves a fundamental problem in AI text transformation: **accuracy versus style tradeoffs**.

| Single-pass risk | Two-pass solution |
|-----------------|-----------------|
| Model over-corrects and invents facts | Verification step catches additions |
| Structural cleanup misses subtle tells | Second pass dedicated to refinement |
| Voice matching interferes with fact preservation | Separation lets each pass focus |

As implemented in `blader/humanizer`, this workflow was introduced in version 2.2.0 and is documented in [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) as the "draft check and second rewrite" pattern.

## Code Examples: Seeing Both Passes in Action

### Simple Inline Rewrite (Both Passes Visible)

```text
/humanizer
[Paste AI-generated text here]

--- Draft rewrite (pass 1) ---
[Humanizer's initial rewrite, still containing a few tells]

--- Final rewrite (pass 2) ---
[Humanizer's polished, human-like version]

```

The draft appears inline so you can observe the transformation. This is useful for understanding which tells were targeted.

### File-Mode Rewrite (Draft Internal Only)

```bash
/humanizer docs/launch-post.md

```

```text

# Humanizer writes only the final prose to the file.

# The draft pass runs internally to ensure no facts are added or lost.

```

When operating on files, Humanizer discards the draft after verification—only the polished version persists.

### Voice-Matching with Author Sample

```text
/humanizer
Here's a sample of my writing:
> "I love crisp sentences—short, sharp, and to the point."

Now humanize this text:
> "The new feature—once hidden—now shines."

```

The **second pass** detects the em-dash preference from your sample and preserves it in the output, even when the draft may have normalized punctuation.

## Key Source Files

Understanding the two-pass process requires examining these files in the repository:

- **[`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md)** – Contains the complete prompt, the enumerated list of tells, and the step-by-step workflow definition (lines 35-38)
- **[`README.md`](https://github.com/blader/humanizer/blob/main/README.md)** – User-facing summary mentioning the draft check and second rewrite introduced in v2.2.0
- **[`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md)** – Packaging specifications ensuring the two-pass logic functions consistently across different agent platforms

## Summary

- Humanizer's **two-pass rewrite process** splits transformation into draft creation and final verification
- **Pass one** removes structural AI tells while preserving all facts
- **Pass two** verifies accuracy and applies voice-matching for stylistic polish
- This architecture, defined in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), minimizes hallucination risk while maximizing human-like output quality
- File paths and version history are tracked in [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) and [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md)

## Frequently Asked Questions

### What are "tells" in Humanizer's first pass?

**Tells are identifiable AI-writing patterns**—structural and rhetorical habits common to large language model output. The first pass in Humanizer marks and targets these for removal. The complete tell taxonomy is documented in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) lines 35-38.

### Can I see the draft output or only the final version?

**You can see both in inline mode**, where Humanizer displays "--- Draft rewrite (pass 1) ---" before the final output. In file mode, only the polished version is written to disk—the draft runs internally for verification without being persisted.

### Does the two-pass process prevent hallucinations?

**Yes, significantly.** The second pass's verification step explicitly checks that no new facts, names, dates, or citations have been introduced compared to the original input. This design catches most accidental hallucinations that single-pass systems miss.

### How does voice matching work across the two passes?

**Voice matching occurs primarily in the second pass.** After structural cleanup in pass one, pass two analyzes any provided writing sample for rhythm, punctuation preferences (like em-dash usage), and sentence length patterns, then applies these to the final output.