# Write Good Fix

> Run write-good to detect weak English prose in comments, docstrings, and documentation, then apply fixes directly using file editing tools. Use when user asks to "fix grammar", "improve writing", "check prose", "fix passive voice", or "run write-good".

- Skill: `albedo-c/write-good-fix` (Agent Skill)
- Install (CLI): `npx skillmds@latest add albedo-c/write-good-fix`
- Raw SKILL.md: https://api.skillmd.com/api/skills/albedo-c/write-good-fix/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: MIT
- Author: albedo-c (https://skillmd.com/u/albedo-c)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/albedo-c/write-good-fix

---


## What I do

- Run `write-good` against all documentation and source files containing English prose
- Interpret every suggestion (passive voice, weasel words, adverbs, etc.) in context
- Edit files directly using file editing tools to improve clarity and directness
- Only touch human-readable prose — never alter code logic, APIs, or variable names

## When to use me

Use this skill when you want to improve the quality of written English in:

- Markdown and RST documentation (`.md`, `.mdx`, `.rst`, `.txt`)
- Python docstrings and `#` comments
- JavaScript/TypeScript JSDoc comments and `//` or `/* */` comments
- YAML/TOML configuration file comments
- README files, CHANGELOG, CONTRIBUTING guides
- Error messages and user-facing strings

**Do NOT use for:** autogenerated files, vendored code, or any file not authored by the project team.

## Step-by-step workflow

### 1. Verify write-good is available

```bash
write-good --version
# or if installed to ~/.local/bin:
~/.local/bin/write-good --version
```

If not installed:

```bash
npm install -g write-good
# or to user prefix (no sudo):
npm install -g write-good --prefix ~/.local
```

### 2. Discover all prose-heavy files

```bash
# Documentation files
find . -type f \( -name "*.md" -o -name "*.rst" -o -name "*.txt" \) \
  -not -path "./.git/*" \
  -not -path "*/node_modules/*" \
  -not -path "*/.venv/*" \
  -not -path "*/dist/*"

# Source files (check comments and docstrings)
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" \) \
  -not -path "./.git/*" \
  -not -path "*/node_modules/*" \
  -not -path "*/.venv/*"
```

### 3. Run write-good on documentation files

```bash
~/.local/bin/write-good --parse *.md docs/**/*.md README.md CONTRIBUTING.md 2>/dev/null
```

Or process files one at a time for focused output:

```bash
~/.local/bin/write-good --parse README.md
```

The output format is:

```
"<offending phrase>" on line X at column Y
-------------
<reason>
```

### 4. Understand what write-good checks

| Check                 | What it flags                       | Example fix                       |
| --------------------- | ----------------------------------- | --------------------------------- |
| **Passive voice**     | "was stolen", "is being used"       | "stole", "uses"                   |
| **Weasel words**      | "very", "quite", "rather", "mostly" | Remove or be specific             |
| **Adverbs**           | "-ly" words that weaken verbs       | Remove or use stronger verb       |
| **"So" at start**     | Sentences beginning with "So"       | Rephrase or remove "So"           |
| **There is/are**      | "There is a problem"                | "A problem exists" or restructure |
| **Lexical illusions** | Repeated words "the the"            | Remove duplicate                  |
| **Clichés**           | "at the end of the day"             | Rephrase directly                 |

### 5. Apply fixes — rules for editing

When fixing prose, follow these principles:

**For passive voice:**

- Change `"The file is read by the parser"` → `"The parser reads the file"`
- Only fix when the active subject is clear and makes the sentence cleaner

**For weasel words:**

- Remove vague qualifiers: `"This is very important"` → `"This is important"` or be specific: `"This prevents data corruption"`
- Replace `"basically"`, `"essentially"`, `"generally"` with precise language

**For adverbs:**

- `"This function quickly processes"` → `"This function processes"` or use a stronger verb: `"This function streams"`

**For documentation specifically:**

- Keep technical accuracy — do not change what a sentence means
- Preserve code spans, links, and formatting exactly
- Do not alter version numbers, command examples, or file paths within prose

**For source code comments:**

- Fix the text inside `#`, `//`, `/* */`, `"""`, `'''` blocks
- Do not touch code on the same line as a trailing comment if the code would be affected
- For multiline docstrings: fix the English but preserve all parameter names, types, and return descriptions exactly

### 6. Process files systematically

For each file with suggestions:

1. Read the full file content first
2. Identify each flagged passage in context
3. Decide: is the suggestion valid? Some flags (especially passive voice in technical docs) are intentionally passive and should be kept
4. Apply the edit using the file editing tool
5. Re-run write-good on the file to confirm the suggestion is resolved

### 7. Review the diff

Before committing, always review all changes:

```bash
git diff
```

For each changed file, verify:

- The fix improves clarity without changing the meaning
- Technical terms, API names, version numbers are preserved
- Links and code examples are intact
- The change is not overly aggressive (e.g., don't change every passive voice if it makes sentences harder to understand)

If any change looks wrong:
- Revert that specific file: `git checkout -- path/to/file`
- Re-evaluate whether the fix should be applied

### 8. Commit the changes

```bash
git add -A
git commit -m "docs: improve prose clarity based on write-good suggestions

Reviewed each suggestion and applied fixes manually.
Addressed passive voice, weasel words, and weak phrasing in comments
and documentation. No functional changes to code logic."```

## Rules and guardrails

- **Never** change code — only prose within strings, comments, docstrings, and documentation
- If a passive construction is a deliberate style choice (e.g. API docs that say "The token is returned"), and changing it makes the sentence less clear, keep it as-is
- Prioritize documentation files first, then source code comments
- Do not apply every single suggestion blindly — use judgment; technical writing sometimes requires constructions write-good flags
- Never rewrite sentences so substantially that the meaning changes
- If you are unsure about a fix, leave the original and add a `<!-- TODO: write-good: ... -->` comment in docs, or `# TODO: write-good: ...` in source