Skip to content
M.[i]
← Skills

shape-blog-post

Shape a blog post

Take a source and shape it into one readable engineering post for this Astro blog.

Source forms:

Form What you receive Shape means
Notes / dictation Messy or half-structured text Order, group, tighten into a post
Draft markdown Pasted markdown or a path to a .md / .mdx file Keep the draft’s meaning and section intent; convert into this site’s MDX + frontmatter

Source rule (hard)

Every claim, example, number, name, and anecdote must trace to the source. Reorder, group, tighten, and rephrase — do not invent meaning.

  • Missing pieces that block a coherent article → ask, then wait.
  • Headings and transitions are structure only (they label what is already there).
  • Frontmatter (title, description, dek, eyebrow, tags, toc, and so on) is distilled from the source, not invented topics.
  • When the source is a draft file, that file is the source of truth for the run (not a prior post on disk unless pointed at).

Plain language

Write for any software engineer on a busy day:

  • Short sentences. Concrete words.
  • Professional and direct — field notes, not a paper.
  • Keep the person of the source (if they wrote “I”, stay in “I”).
  • Prefer terms a mid-level engineer already knows; define a term only when the source defines it.

High-level workflow

  1. Collect the source — full notes, paste, or a named path. Read files before outlining. If there is no body and no path, ask and stop.
  2. Outline from the source only — topics that are actually present; order for a human reader (why it matters → main points → takeaways only if present). Every outline bullet maps to a source passage; nothing the author meant to keep is dropped.
  3. Write the MDX draft — site blog path and frontmatter from the content schema; body as plain engineering prose with site section patterns. draft: true for skill output. No claims beyond the source.
  4. Diagrams only when asked — labels and stages from the source (or explicit diagram notes); no extra nodes for “completeness.”
  5. Hand back — path of the draft, section outline, unplaced source points, real open questions. Do not publish, undraft, or commit unless asked.

Fidelity

Meaning comes only from the source. Structure and clarity improve; the story does not grow.