write-good-fix

name: write-good-fix description: 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". version: 1.0.0 license: MIT compatibility: opencode, claude metadata: tool: write-good tool_version: ">=1.0" workflow: inline-edit

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

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