# Blog Reviewing

> Use when reviewing, auditing, or preparing blog posts for publication. Triggers include checking post consistency, reviewing drafts, or auditing all posts against blog standards.

- Skill: `jonesrussell/blog-reviewing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jonesrussell/blog-reviewing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jonesrussell/blog-reviewing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jonesrussell (https://skillmd.com/u/jonesrussell)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jonesrussell/blog-reviewing

---


# Blog Reviewing

## Overview

Systematically audit blog posts against the canonical style rules defined in the blog-writing skill. Every review follows the same checklist — no ad-hoc exploration.

**Canonical authority:** The style rules in `.claude/skills/blog-writing/SKILL.md` and `docs/blog-style.md` are the source of truth. Read both before reviewing. Reference post: `content/posts/laravel-boost-ddev.md`.

## Review Process

1. Read the blog-writing skill and `docs/blog-style.md` to load current rules
2. Identify the post type (series or general) from frontmatter `series` field
3. Run through the checklist below in order
4. Report findings using the standard format
5. **Auto-generate social copy if missing** — if `docs/social/{slug}.md` does not exist, generate it now using the Social media artifact rules in the blog-writing skill. Do not just flag it as MISSING and move on.

## Checklist

Run every check. Do not skip items.

### Frontmatter

- [ ] `title` present, sentence case, descriptive
- [ ] `date` in YYYY-MM-DD format
- [ ] `categories` present, lowercase, hyphenated for multi-word
- [ ] `tags` present, **max 4**
- [ ] `summary` field used (not `description`). One sentence: outcome or audience.
- [ ] `slug` present, kebab-case
- [ ] `draft` field present
- [ ] **Series posts only:** `series` field present with correct series name

### Structure

- [ ] Opens with "Ahnii!" (exclamation mark, own paragraph)
- [ ] Closes with "Baamaapii" (no emoji, own paragraph)
- [ ] Intro states what the post covers in one sentence (scoped)
- [ ] Intro covers the relevant W's: **What** (what the reader learns), **Why** (why it matters or what problem it solves), **Who** (who it's for, if not obvious from context). Not all W's are required — use judgment based on post type.
- [ ] No "Wrapping Up" or "Conclusion" heading
- [ ] No time estimates in section headings
- [ ] Heading hierarchy: H2 for main sections, H3 for variants/subsections
- [ ] Prerequisites section (bullet list) when relevant

### Series Index Structure (only if `series_order: 0`)

- [ ] `series_order: 0` in frontmatter
- [ ] 1-2 sentence intro stating what the series covers and who it's for
- [ ] Numbered H3 TOC listing every post in the series
- [ ] Published posts (date <= today) use `relref` links
- [ ] Future-dated posts use plain text titles (no `relref`)
- [ ] Each TOC entry has 1-2 sentence description
- [ ] TOC order matches `series_order` values across the series

### Series Post Structure (only if `series` field exists and `series_order` > 0)

- [ ] Prerequisites blockquote after greeting
- [ ] Problem statement section
- [ ] Core concepts/interfaces section with code
- [ ] Real-world implementation section
- [ ] Common mistakes section with bad/good code pairs
- [ ] Framework integration section
- [ ] Try it yourself section with companion repo commands
- [ ] What's next section linking to next post in series

### Series Consistency (only if `series` field exists)

- [ ] "Part N" references in body text match `series_order` in frontmatter
- [ ] "Next" teaser points to the correct next post (by `series_order`, not by topic similarity)
- [ ] "Next" link uses `relref` (or plain text if the target post is future-dated)
- [ ] No duplicate dates with other posts in the same series
- [ ] Series index post (`series_order: 0`) exists and lists all posts in the series

### Content

- [ ] All code blocks have language tags
- [ ] After each code block: 1-2 sentences explaining what it does or why
- [ ] First mention of products/tools/projects is linked
- [ ] Internal links use `relref` shortcode (e.g., `{{< relref "post-slug" >}}`), not root-relative paths
- [ ] External links use full HTTPS URLs
- [ ] Voice is second person, direct, instructional ("you"/"your", not "I"/"my")
- [ ] Concise: short sentences, one idea per paragraph, no filler
- [ ] Em dashes used intentionally and sparingly (one or two per post max; zero is fine)
- [ ] Contrast constructions like "X is not Y, it is Z" are used intentionally, not repeated as a crutch
- [ ] Sentence cadence varies enough that the draft does not read mechanically repetitive
- [ ] Generic AI-jargon filler ("robust", "seamless", "transformative", "momentum") is replaced with concrete wording
- [ ] Headings are SEO-friendly with keywords (not generic like "The Problem" or "The Full Picture")
- [ ] Tags match post content (every tag should be substantiated in the body)
- [ ] Wordy flow/pipeline/architecture explanations replaced with Mermaid diagrams (3+ sentences describing a flow or component relationship is a signal to use a diagram instead)
- [ ] Named concepts (interfaces, classes, patterns) are explained in plain language before being introduced by name
- [ ] Prose doesn't narrate what adjacent code already shows (if a bullet list describes what a method does and the code block shows the same thing, delete the list)
- [ ] Behavioral claims ("you can do X", "this prevents Y") are backed by a code example showing the behavior

### Visual Components

- [ ] Numbered lists with 3+ items where each item has explanatory content → suggest `steps` shortcode
- [ ] Inline link CTAs at the end of a project-showcase post → suggest `cta` shortcode
- [ ] Asides or warnings written as bare paragraphs → suggest `callout` shortcode
- [ ] More than one `pullquote` shortcode per post → flag as INCORRECT (max one per post)
- [ ] More than one `cta` shortcode per post → flag as INCORRECT (max one per post)
- [ ] Component used decoratively without adding information → flag as INCORRECT (walls of decoration are worse than walls of text)
- [ ] `compare` used for non-before/after contrasts → flag as INCORRECT (use a markdown table instead)
- [ ] `stats` used in a post without real metrics → flag as INCORRECT (don't invent numbers)

## Findings Format

Report each finding as:

```
**[CATEGORY]** Line N: description
  Fix: exact correction
```

**Categories:**
- **MISSING** — Required element is absent
- **INCORRECT** — Element exists but violates a rule
- **SUGGESTION** — Not a rule violation, but would improve the post

Always include the line number and a specific fix. Do not report findings without both.

**Example:**
```
**MISSING** Line 50: No farewell. Post ends without "Baamaapii"
  Fix: Add "Baamaapii" as the final line, on its own paragraph

**INCORRECT** Line 13: Greeting uses comma ("Ahnii,") instead of exclamation mark
  Fix: Change "Ahnii," to "Ahnii!"

**INCORRECT** Line 102: Farewell has emoji ("Baamaapii 👋")
  Fix: Change to "Baamaapii" — no emoji
```

### Accuracy

- [ ] All code blocks are syntactically correct
- [ ] Code referencing specific projects matches actual source in that repo
- [ ] Tool/product names are correct and current
- [ ] Internal links have matching slugs that exist
- [ ] External links use valid HTTPS URLs
- [ ] Behavioral claims ("this does X", "the output looks like") are verifiable
- [ ] Config/file references match actual state in referenced repos
- [ ] No aspirational state presented as current state
- [ ] Code referencing repos in `~/dev/` has been verified against the actual source (AI-generated interface signatures, method names, and class names are frequently hallucinated)

### Social Media Artifact

- [ ] Companion file exists at `docs/social/{slug}.md` — **if missing, generate it now** (do not flag and skip)
- [ ] Canonical URL present and correct (`https://jonesrussell.github.io/blog/{slug}/`)
- [ ] Facebook: 1-3 sentence hook + link + hashtags
- [ ] X (Twitter): under ~240 characters including URL, link at end
- [ ] LinkedIn: professional tone, no hashtags, link included
- [ ] All platform blocks include the canonical URL

## Self-Improving Audit Loop

After completing a review, check whether any finding was **not already covered** by an existing checklist item or common mistakes entry. If so:

1. Add the new check to the appropriate skill file:
   - New checklist item → `~/dev/skills/skills/blog-reviewing/SKILL.md`
   - New common mistake → `~/dev/skills/skills/blog-writing/SKILL.md` (Common Mistakes table)
   - New style rule → both files as appropriate
2. Sync the updated skill to the installed copy at `~/.claude/skills/blog-*/SKILL.md`
3. The PR review process on the `~/dev/skills/` repo is the human gate for accepting or rejecting new rules

This ensures every review session that discovers a gap automatically improves future reviews.

## Batch Mode

When asked to review multiple posts:

1. List all target posts (e.g., all drafts: `grep -rl "draft: true" content/posts/`)
2. Identify each post's type (series vs general)
3. Review each post against the checklist
4. Group findings by post with a summary count

**Output format for batch:**
```
## [post-slug.md] — [N findings: X missing, Y incorrect, Z suggestions]
[findings]

## [post-slug.md] — [N findings: ...]
[findings]
```