article-review

name	article-review
description	Publish-readiness review for blog posts — content, structure, flow, typos, demos, code, SEO, facts, and STYLEGUIDE compliance. Use when the user asks to review, proofread, or audit an article or draft before publishing.

Article Review

Goal: determine whether a post is ready to go live. Read STYLEGUIDE.md for editorial and formatting rules; apply them without restating them in the report. This skill adds publish-readiness checks beyond the styleguide.

Workflow

1. Identify the target — posts/YYYY-MM-DD-slug.md, editor draft, or pasted content.
2. Read STYLEGUIDE.md — Especially Editorial checklist and Things to avoid.
3. Read the full article — Front matter, body, Liquid shortcodes, footnote assigns, embedded demos, code blocks.
4. Follow references — Open linked posts, demo files under includes/demos/, cited source URLs, and GitHub permalinks when claims or code depend on them.
5. Verify what you can — Asset paths exist; demo partials resolve; internal URLs use /YYYY/MM/DD/slug/ form. Run npm start or npm run build when interactively verifying demos, anchors, or rendered output is needed.
6. Report — Use the output format below. Quote short excerpts; propose concrete fixes.

Review dimensions

Content and accuracy

• Does the post deliver what the title and description promise?
• Are technical claims accurate? Trace APIs, flags, versions, and behavior against docs or the linked repo when possible.
• Flag unsupported claims, outdated information, internal contradictions, and logical gaps (missing steps, non sequiturs, causation without evidence).
• Distinguish opinion from fact; opinions should be reasoned, not presented as universal truth.
• Credit sources; ensure attributions match Links conventions.

Structure and reading flow

• Opening hooks without restating the title (Document structure).
• Section order makes sense; each ## earns its place; no orphaned or redundant sections.
• Heading hierarchy is logical (## → ###, no skipped levels).
• Paragraph length and pacing: no walls of text; dense stretches broken up appropriately.
• Closing reflection (Wrapping up / Lessons learned / etc.) — not a bullet recap of the whole post.
• Transitions between sections; reader always knows why the next section exists.

Editorial style and formatting

Work through STYLEGUIDE sections; cite the section name when flagging (e.g. “Footnotes”, “Things to avoid”). Run the Editorial checklist and report only failures.

Includes: voice, locale, typography, links, figures, callouts vs blockquotes, footnotes, code block conventions, lists.

Typos and copy-editing

• Spelling (American English per styleguide).
• Grammar, punctuation, curly quotes, en/em dashes used appropriately.
• Consistent terminology within the post (product names, acronyms after first <abbr>).
• Front matter title in APA title case; description is one clean sentence.

Code snippets

• Snippets match what the prose describes; no stale or misleading examples.
• Language tags present; indentation uses tabs (Code blocks).
• Liquid in fences is escaped ({% raw %} or zero-width spaces).
• Focused blocks with // … where appropriate; teaching comments explain intent, not mechanics.
• When the post references production code, spot-check the linked file or path if available.
• Flag security-sensitive patterns only when clearly wrong for the context (hardcoded secrets, dangerous copy-paste).

Demos

Posts embed demos via {% render "demos/…" %}.

For each embed:

• Confirm the partial exists under includes/demos/.
• Read associated script.js, styles.css, data.js when the article discusses their behavior.
• Prose around the demo should explain what to try and what to notice (context before; interpretation after if needed).
• Flag broken paths, missing noscript warnings where JS is required, or demos that contradict the article.
• If the article teaches something interactive but has no demo (and similar posts in the archive use one), note it as a Consider — not a blocker unless the post explicitly promises interactivity.

Do not build new demos during review unless the user asks; only assess existing ones.

SEO and discoverability

Front matter drives meta tags and OG cards (see tests/head.test.ts).

• title — clear, accurate, APA title case, no trailing period.
• description — single sentence; works as OG/RSS summary; not a keyword dump.
• tags — Title Case; reuse existing tags where sensible.
• image — path set and file exists under assets/images/<slug>/. Flag if missing; do not generate (use the article-image skill when asked).
• Filename YYYY-MM-DD-kebab-case-slug.md matches intended publish date and URL.
• draft: true should be removed before publish.
• First paragraph and headings give enough context for search and social previews.

Assets and build

• Figure paths under /assets/images/<slug>/; meaningful alt distinct from caption.
• No bare Markdown images; CodePen embeds use codepen.liquid when present.
• Note if a local preview build is recommended to confirm anchors, demos, or footnote rendering.

Severity

• Must fix — Blocks publish: factual errors, broken links/paths, missing required front matter, styleguide violations with wrong semantics (blockquote vs callout, bare images, spaces in code blocks), misleading code, broken or missing demo files referenced in the post, draft: true left on, missing alt.
• Should fix — Weakens the post materially: poor flow, vague claims without support, SEO description weak or wrong length, voice drift, checklist gaps, code that doesn’t match prose, demo lacks context.
• Consider — Polish: tighter prose, optional demo, friendlier closing, fewer em dashes, optional OG image format upgrade (AVIF/WebP per styleguide).

Output format

# Review: [Post title]

**File:** `posts/…`
**Verdict:** Ready to publish | Needs revision | Major rework

## Summary
[2–4 sentences: readiness, main blockers, overall quality.]

## Must fix
- **[Category]** — `excerpt…` → fix.

## Should fix
- …

## Consider
- …

## Publish checklist
- [ ] Editorial checklist (STYLEGUIDE) — pass / N items failing
- [ ] Content accurate and complete
- [ ] Code and demos verified
- [ ] SEO front matter (`title`, `description`, `tags`, `image`)
- [ ] `draft` removed, filename/date correct
- [ ] Local preview (`npm start`) if demos or anchors need human check

## Strengths
[1–3 specific positives.]

Keep findings actionable. Do not dump STYLEGUIDE content into the report.

When asked to fix

Apply minimal diffs for agreed findings. Re-read changed sections. For factual or technical corrections, confirm with the author when uncertain rather than inventing details.

Out of scope

• Generating OG/cover images — flag absence only; use article-image when the user wants one created.
• Rewriting for a different angle unless asked — review improves readiness, not the thesis.
• Deploying or committing — unless explicitly requested.