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

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

If not installed:

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

2. Discover all prose-heavy files

# 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

~/.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:

~/.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:

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

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