Article Review

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.