| 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
- Identify the target —
posts/YYYY-MM-DD-slug.md, editor draft, or pasted content.
- Read STYLEGUIDE.md — Especially Editorial checklist and Things to avoid.
- Read the full article — Front matter, body, Liquid shortcodes, footnote assigns, embedded demos, code blocks.
- Follow references — Open linked posts, demo files under
includes/demos/, cited source URLs, and GitHub permalinks when claims or code depend on them.
- 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.
- 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.
