proofread-blog

name	proofread-blog
description	Proofread blog articles for typos, errors, readability, and logical consistency. Use when reviewing blog posts before publication.
disable-model-invocation	false
allowed-tools	Read, Grep, Glob, Edit, Bash

Blog Article Proofreading

This is the draft of a blog article I am about to publish.

Critical Standards

Be direct and critical. Do not LLM-nod through the content. If something is:

• Lazy or hand-wavy → Say it's lazy
• Poorly argued → Call it out as weak
• Illogical → Point out the logical flaw
• Repetitive or circular → Flag it

But don't be contrary for the sake of it. Focus on genuine issues, not manufactured problems.

Exception: Learning in Public When the article explicitly signals that I'm learning/exploring a new subject (phrases like "I'm new to X", "learning about Y", "first time trying Z"), adjust criticism accordingly:

• Still catch typos and factual errors
• Flag actual misconceptions that could mislead readers
• But don't hammer tentative conclusions or exploratory thinking
• Recognize that uncertainty and questions are features, not bugs, in learning posts

Primary Tasks

1. Typos - Check the article thoroughly to catch everything. I write in en-gb. Do not challenge en-gb spellings.

   • Note: automagically is intentional and good
   • Offer to fix typos using the Edit tool
   • If you let any typos through, you have failed.

2. Factual errors or inconsistencies - Be ruthless here

3. Readability - Brief but honest assessment. My voice is technical yet informal, aimed at developers. I use colloquialisms and snark. But if the writing gets convoluted or loses its thread, say so.

4. Logic and Arguments - This is where you should be most critical:

   • Highlight lazy arguments ("it just works better")
   • Call out unsupported claims
   • Flag inconsistent reasoning
   • Point out when I'm hand-waving through complexity
   • Identify where I've made leaps without evidence

5. Focus and Structure - Assess whether the post is trying to do too much:

   • List the distinct purposes the post is serving (e.g., "explain why X matters", "tutorial on Y", "share experience with Z", "provide tips")
   • If there are more than 2-3 core purposes, flag this explicitly
   • Common split: thinking posts (why X matters, mental models, opinions, philosophy) vs doing posts (tutorials, hands-on examples, practical how-to). These often work better as separate pieces.
   • Ask: Would this be stronger as two focused posts rather than one sprawling one?
   • Watch for scope creep where the post starts conceptual and morphs into tutorial (or vice versa)
   • A post that tries to do 8 things does none of them well

If the article is genuinely solid, say so. But if it's not, be specific about what's wrong.

Ignore the header and footer content.

Report any hardcoded links to rmoff.net; prefer relative links.

6. Image alt text - Check all images for missing or empty alt text. For each image without alt text, suggest concise, descriptive alt text based on the image content and surrounding context. In AsciiDoc, images without alt text look like image:/path/to/image.png[] — the alt text goes inside the brackets: image:/path/to/image.png[Description of the image]. Read the image files to see what they contain before suggesting alt text.

7. AsciiDoc markup pitfalls - Check for common AsciiDoc rendering issues:

   • Underscore mangling in link anchors: link:/path/#_some_anchor[text] — AsciiDoc interprets _word_ sequences as italic markup, turning anchors like #_joining_the_data into #<em>joining_the_data. Fix with pass:[]: link:/path/#pass:[_some_anchor][text]
   • Underscore mangling in inline content: Backtick-quoted identifiers containing underscores (e.g., `_fieldName`) can get italic-mangled if not properly escaped. Watch for any _text_ patterns inside or adjacent to inline code that might be misinterpreted as emphasis.
   • SQL query + results in code blocks: When a code block contains both a SQL statement and its tabular output, they should be split into two consecutive blocks: [source,sql] for the query and [source,text] for the results. The CSS will visually join them with a dashed separator. Never combine a SQL statement and its table output in a single [source,sql] block — the syntax highlighting mangles the box-drawing characters. Remove any > shell prompts from the SQL when splitting.

8. Image format and size - All images should use WebP format for optimal file size. Check the article's frontmatter (image, thumbnail, socialimage) and any inline image: references.

   • If any referenced images are not WebP (e.g., PNG, JPEG), convert them using magick:
     • Frontmatter image (hero/banner image): resize to 1800px width and convert to WebP with h_ prefix:

       magick input.png -resize '1800x>' -quality 80 h_input.webp
       

     • Frontmatter thumbnail: resize to 800px width and convert to WebP with t_ prefix:

       magick input.jpg -resize '800x>' -quality 80 t_input.webp
       

     • Inline images (body image: references): convert to WebP without resizing:

       magick input.png -quality 80 output.webp
       

     • The -resize '...>' flag means "only shrink, never enlarge".
   • After converting, update all references in the article (frontmatter and body) to point to the new .webp files.
   • Do NOT delete the original files — keep them alongside the WebP versions.
   • Report what was converted and the file size savings.

9. Category taxonomy - Check the post's categories are consistent with existing usage:

   • Run: grep -h -A 20 '^categories:' content/post/*.adoc content/post/*.md | grep '^- ' | sed 's/^- //' | sort | uniq -c | sort -rn
   • Compare the current post's categories against that list
   • Flag categories that have never been used before — ask if intentional or a typo
   • Flag categories that look like near-duplicates of existing ones (e.g., "Claude" vs "Claude Code", "kafka" vs "Kafka", "VisiData" vs "visidata")