WrongoDB Blogging

Overview

Create blog post plans and drafts for the WrongoDB series without re-reading or re-deriving the series structure. Use the canonical prompts embedded below and the image generator script in this repo.

Workflow (plan -> write -> images)

1) Planning a post

• Read the "Planning prompt (canonical)" section below and follow it exactly.
• Before locking the topic, grab inspiration from recent work:
  • Scan git history beyond the last 20 commits and pinpoint the relevant change:
    • git log --oneline --reverse --since="2025-12-01" (widen/narrow dates as needed)
    • git log --oneline -- src/blockfile.rs src/leaf_page.rs src/btree.rs docs/decisions.md (file-focused)
    • git log -S "BlockFile" -S "FULLFSYNC" -S "checkpoint" -S "slot" --oneline (string-focused)
  • Cross-check PLAN.md, docs/decisions.md, blog/SERIES.md
  • Codex session logs for narrative hooks: ~/.codex/sessions and ~/.codex/history.jsonl (use rg for keywords like blockfile, fs_usage, BTree, checkpoint)
• Do not reread or re-discover prior posts; the prompt already encodes the structure and voice.
• Produce a plan with the required sections (Title + hook, scope, 7 beats, decisions, artifact, images, verification).
• If details are uncertain, tag as TO VERIFY.
• Outline clarity guidelines (apply when the user asks for simpler language or stronger pedagogy):
  • Reduce jargon and define any unavoidable terms in plain language.
  • Add a one-sentence definition for the core concept (e.g., “A B+tree is…”).
  • Deepen the “Why” beyond the immediate symptom (e.g., not just “page full,” but why the structure is a standard DB building block).
  • Keep each beat short and explanation-forward (one or two sentences max).
• Aha-moment mining (when planning or revising posts):
  • Scan ~/.codex/sessions and ~/.codex/history.jsonl for the exact questions/confusions you had (e.g., “what the hell is a slot,” “when do we compact?”).
  • Extract 2–4 of those questions and answer them in the post as short, teachable inserts.
• Image planning lessons:
  • Diagram refinement loop (use for diagrams, not photos):
    1. Why: state the diagram’s purpose in one sentence.
    2. Story: spell out the specific point the diagram must teach.
    3. Draft: list visual elements, color roles, connections, icons, and style choices.
    4. Refine: improve hierarchy, notation consistency, aesthetics, and remove extra complexity.
    5. Verify: check the diagram matches the intended concept and is correct.
  • Each image prompt must state the story purpose (e.g., “show the durability boundary” or “map trace lines to meaning”), not just the subject.
  • Prefer narrative structures (before/after, timelines, mappings) over generic box-and-arrow diagrams.
  • Specify labels and icons that reinforce the story (e.g., crash bolt, shield, timeline bands).
  • After generation, validate files are real images (file blog/<post-dir>/images/*.png); if invalid or dull, revise prompts and regenerate.
• Story/structure lessons:
  • After any significant change anywhere, re-check that the arc still flows.
  • Prefer a narrative arc that moves from problem → shape/mental model → key rule/decision → operations (insert/delete) → concrete bytes → boundary/implication → why it matters.
  • Introduce new concepts inline before using jargon; keep definitions direct (no metaphors).
  • Use sections for readability; include explicit transitions or “lightbulb” moments where they help.
  • Diagrams must be narrated in the text and placed near the concept they illustrate.
  • Include a brief “how I ran the tool” line in the post when a tool is central; mention other options you did not use.
• Keep series continuity: add a short recap/link to the previous post when relevant; ensure numbering/order is updated.

2) Writing a post

• Read the "Writing prompt (canonical)" section below and follow it exactly.
• Use the plan as the single source of truth; do not add new slices.
• Keep the voice candid, playful, learning-first, “wrong on purpose.”
• Keep the body tight (5–10 minute read).
• Include the images specified in the plan.

3) Generating images

• For each image prompt, run: python blog/generate_image.py "<prompt>" --post <post-dir> --out blog/<post-dir>/images/<NN-short-name>.png
• Prefer agentic mode for diagrams (draft → generate → critique → revise): python blog/generate_image.py "<prompt>" --post <post-dir> --out blog/<post-dir>/images/<NN-short-name>.png --agentic --iterations 2
• Prefer sizes/aspects by intent:
  • Hero: --aspect 16:9 --size 2K
  • Diagrams: --aspect 4:3 --size 1K or --aspect 1:1 --size 1K
• Filenames must be prefixed with the order they appear in the post: 01-, 02-, 03-, ...
• If an image prompt is unclear, revise the prompt text first (do not guess).
• Agentic mode writes a sidecar JSON file next to the image with draft/final prompts and critique summaries; use it to judge story effectiveness, visual consistency, and pleasing aesthetics.

4) Generating diagrams with HTML intermediate (RECOMMENDED for structured diagrams)

When diagrams have structural quirks (misaligned elements, wrong layouts), use the HTML-intermediate approach. This generates HTML/CSS representing the diagram structure, renders it via Playwright, and uses the result as a visual reference for final image generation.

Why this helps:

• CSS Grid/Flexbox provides reliable, predictable layouts
• AI models are extensively trained on HTML/CSS
• Multi-panel diagrams work correctly with CSS Grid
• The image model sees a concrete layout reference instead of inferring from text
• Reduces "hallucinated" layouts and misaligned elements

Workflow:

# Generate diagram using HTML intermediate
python blog/generate_image.py "<diagram description>" --post <post-dir> --out blog/<post-dir>/images/<NN-name>.png --structured --save-html

# Multi-panel diagram (auto-detected from description)
python blog/generate_image.py "4-panel diagram showing Panel 1) ..., Panel 2) ..., Panel 3) ..., Panel 4) ..." \
  --post <post-dir> --out blog/<post-dir>/images/<NN-name>.png --structured --save-html

# Use different models for HTML vs final image (faster/cheaper HTML generation)
python blog/generate_image.py "<diagram description>" --post <post-dir> --out blog/<post-dir>/images/<NN-name>.png \
  --structured --html-model gemini-2.5-pro --save-html

Options:

• --structured: Enable HTML/CSS intermediate mode for structured diagrams
• --save-html: Save intermediate HTML and its rendered PNG reference
• --html-model <model>: Model for HTML generation (defaults to --model, use gemini-2.5-pro for faster/cheaper HTML)
• --aspect 4:3, 16:9, or 1:1: Diagram aspect ratio (default: 16:9)
• --size 1K, 2K, or 4K: Output size (default: 2K)

Prerequisites:

pip install playwright google-genai
playwright install chromium

How it works:

1. Generate HTML/CSS from the prompt (structural layout with labels, boxes, arrows)
2. For multi-panel: generate separate HTML for each panel, combine in CSS Grid
3. Render HTML via Playwright (this is the "reference" layout)
4. Generate final image using the reference as a visual guide
5. (Optional) Critique final image against reference for structural accuracy

When to use:

• Complex structural diagrams (B-tree pages, memory layouts, flowcharts)
• Multi-panel progression diagrams (before/after, step-by-step)
• When standard agentic mode produces misaligned elements
• Diagrams with specific spatial relationships that matter

When NOT to use:

• Hero images, photos, or conceptual art (use generate_image.py instead)
• Simple diagrams where structure is less critical

QA checklist

• Keep TO VERIFY tags until verified against code or notes.
• Confirm the plan matches the thin-slice scope.
• Ensure images were generated with blog/generate_image.py (photos/heroes, diagrams with --structured), stored under blog/<post-dir>/images/, and filenames match the post markdown.

---

Planning prompt (canonical)

Blog Post Planning Prompt (WrongoDB series)

Use this prompt to plan a new post in the WrongoDB devlog series.

---

Goal

Produce a tight, publish-ready plan for a single new post (5–10 minute read) that advances the series by one thin slice.

Known series DNA (do NOT re-derive)

• Voice: candid, playful, learning-first
• Structure rhythm: hook → context → mental model → one key decision → concrete artifact → why it matters → what’s next.
• Teaching moves: rhetorical questions, crisp definitions, zoom from concept to bytes, explicit layer separation.
• Visual rhythm: 2–4 images per post
• Scope: one slice only, no roadmap dumps.

Planning rules

• Plan the next post using the structure above
• Pick one core concept and one key decision to explain, if not provided by the user.
• Include one concrete artifact to anchor the explanation (code, struct, layout, file header, algorithm step, etc.).
• Prefer examples that can be verified against the repo if needed.
• If details are uncertain, mark as TO VERIFY (do not invent).

Output format

Return a plan with the following sections, in order:

1) Title + Subtitle + One-line hook

• Proposed title
• A meaningful subtitle that sharpens the focus (not a generic label)
• A single-sentence hook that sounds like the existing voice

2) Thin-slice scope

• One sentence: “This post explains … and stops before …”

3) Outline (7 beats)

Use exactly these beats:

1. Hook
2. Context / Why this exists
3. Mental model (diagram candidate)
4. Key decision (trade-off + rationale)
5. Concrete artifact (code/struct/layout)
6. Why it matters (behavior + invariants)
7. What’s next (2–3 bullets)

4) Key decisions

• Decision: …
• Alternatives considered: … (2–3 options max)
• Trade-offs: …

5) Concrete artifact

• Name the artifact and where it lives (file path or conceptual object)
• Bullet list of the 2–4 elements you will show or explain

6) Images

• 2–4 image prompts (short, literal)
• Include the intended filename for each image with an ordered prefix (e.g., 01-..., 02-...)

7) Verification checklist

• 3–6 bullets of facts to verify against code/notes
• If anything is speculative, tag it TO VERIFY

---

Style constraints for the plan

• Keep each section short; avoid narrative prose.
• Prefer plain language; avoid jargon unless defined.
• If the topic is concept-heavy, include a one-sentence definition in the plan.

Example: acceptable brevity (mini)

• “Key decision: explicit allocation vs implicit append; trade-off: clarity vs convenience.”

---

Writing prompt (canonical)

Blog Post Writing Prompt (WrongoDB series)

Use this prompt to write a full post from an existing outline created with the planning prompt above. Do not reread or re-discover the existing posts. The structure and voice are already known and summarized here.

---

Inputs

You will be given a plan that follows the 7-beat outline and includes:

• Title + One-line hook
• Thin-slice scope
• Outline beats
• Key decisions
• Concrete artifact
• Images
• Verification checklist

Goal

Produce a complete markdown post that follows the plan exactly, in the established voice and structure, and is ready to drop into blog/NN-title.md.

Known series DNA (do NOT re-derive)

• Voice: candid, playful, learning-first, “wrong on purpose.”
• Structure rhythm: hook → context → mental model → one key decision → concrete artifact → why it matters → what’s next.
• Teaching moves: rhetorical questions, crisp definitions, zoom from concept to bytes, explicit layer separation.
• Visual rhythm: 2–4 images per post.
• Scope: one slice only, no roadmap dumps.

Writing rules

• Follow the plan’s 7 beats in order.
• Do not add new topics or extra slices.
• Include 2–4 inline images as markdown: ![Alt](images/<NN-filename>.png).
• Image filenames must be prefixed in order of appearance: 01-, 02-, 03-, ...
• For photos/hero images: python blog/generate_image.py "<prompt>" --post <post-dir> --out blog/<post-dir>/images/<NN-short-name>.png
• For technical diagrams (especially trees or multi-panel): python blog/generate_image.py "<prompt>" --post <post-dir> --out blog/<post-dir>/images/<NN-short-name>.png --structured --save-html
• If a fact is uncertain, mark it inline as TO VERIFY and keep going.
• Do not invent code details; only reference file paths or structs if the plan says they exist.
• Avoid markdown links unless the plan explicitly provides them.

Output format

Return a single markdown document with:

1. # Title
2. ## Subtitle
3. Optional hero image (if the plan calls for it)
4. Body sections in a natural flow (no numbered headings required)
5. “What’s next” as a bullet list

Style constraints

• Tight paragraphs (3–6 lines each)
• Occasional rhetorical questions
• Definitions in short, punchy sentences
• Avoid marketing language

Post template (skeleton)

<Title>

<Subtitle>

<Hook paragraph>

<Context / why this exists>

<Mental model + image>

<Key decision + trade-off>

<Concrete artifact explanation> <Why it matters>

What’s next

• <bullet>
• <bullet>
• <bullet>

---

After writing

• Ensure all TO VERIFY flags are still present (do not resolve them).
• Ensure all images mentioned in the plan are included.
• Ensure each image was generated with blog/generate_image.py (photos/heroes, diagrams with --structured), stored under blog/<post-dir>/images/, and matches the prompt.
• Ensure the post matches the thin-slice scope.