Skip to content

CHECKLIST.md

Latest commit

 

History

History
71 lines (46 loc) · 4.11 KB

CHECKLIST.md

File metadata and controls

71 lines (46 loc) · 4.11 KB

Self-verification checklist for magazine articles and blog posts

Walk this checklist after you have written a draft and before you ship. Each item names the rule file with the precise pass/fail criteria.

The checklist is ordered for efficiency: structural fail rules first (cheap to detect, blocking), then warn rules in roughly the order an editor reads the article.

Stage 1 — structural FAIL rules (must pass)

  • Opening hook in first 200 words — engagement/DF-040-opening-hook.md
  • Every conceptual H2 has an example or code block — engagement/DF-042-concrete-examples.md
  • Every image has alt text — visuals/DF-058-image-alt-text.md
  • Every relative image path resolves — visuals/DF-059-image-paths-resolve.md

If any of these fail, fix them before continuing — they are publication blockers.

Stage 2 — engagement (warn)

  • Each H2 opens with a question or problem framing — engagement/DF-041-question-before-answer.md
  • No placeholder names in code (foo, bar, acme) — engagement/DF-043-no-placeholder-names.md
  • Article ends with a forward-linking section — engagement/DF-045-next-steps.md
  • At least 50% of section transitions are bridged — engagement/DF-046-section-transitions.md
  • Setup → confrontation → resolution arc is visible — engagement/DF-047-narrative-arc.md

Stage 3 — voice (warn)

  • Passive voice under 20% — voice/DF-052-active-voice.md
  • "you" appears at ≥ 50% of system-phrase rate — voice/DF-053-reader-focus-you.md
  • All forms contracted — llm-artifacts/contractions.md
  • Topic sentence frontloaded in every paragraph — voice/DF-055-frontload-topic-sentence.md

Stage 4 — cognitive load and readability (warn)

  • Every paragraph ≤ 5 sentences — cognitive-load/DF-030-paragraph-length.md
  • Every list 3–7 items — cognitive-load/DF-031-list-length-max.md, DF-032-list-length-min.md
  • Every section ≤ 500 words — cognitive-load/DF-033-section-density.md
  • Average sentence ≤ 25 words; cap at 30 — readability/DF-051-sentence-length.md
  • Flesch-Kincaid grade ≤ 8 — readability/DF-050-flesch-kincaid.md (use CLI for the number)
  • No bare "Overview" / "Details" / "Conclusion" headings — readability/DF-054-descriptive-headings.md

Stage 5 — visuals (warn)

  • Dense conceptual or structurally-named sections include a visual or [IMAGE: ...] marker — visuals/DF-056-visual-support-density.md

Stage 6 — LLM artefact removal (warn, but non-negotiable for magazine quality)

This is the single most important pass for magazine readability. Do all four:

  • No words from the 50+ overused-word kill list — llm-artifacts/overused-words.md
  • No phrases from the 20+ filler-phrase list — llm-artifacts/filler-phrases.md
  • No em dashes, smart quotes, decorative emoji — llm-artifacts/typographic-artifacts.md
  • No sentence starts with "Furthermore,", "Moreover,", "Notably," — llm-artifacts/conjunctive-adverb-openers.md

Stage 7 — read it aloud

Read the first sentence of every paragraph in order. Does that summary alone make sense as a synopsis of the article? If yes, the topic sentences are frontloaded. If no, return to voice/DF-055-frontload-topic-sentence.md.

Read the H2 outline in order. Does it tell the story arc? If no, return to engagement/DF-047-narrative-arc.md.

Read the opening 200 words and the closing 100. Do they bookend the same idea? If no, the closing is wandering — see engagement/DF-045-next-steps.md.

Optional — numeric confirmation via CLI

docflow validate <file> --engagement-report

Targets: 90+ in each of the five dimensions (curiosity, clarity, action, flow, voice). See PROFILES.md for what feeds each dimension.

When the checklist passes

The article is ready for human review. See src/templates/agents.md for the human-review gate, mode contracts (single / role-based / consensus), and the ## Agent Contributions section format that every artifact must end with.