--- name: blog-writing description: Use when writing a technical blog post from a BLOG_HANDOFF.md document. Triggers on "write the blog", "draft the post", "blog from handoff", "turn this into a blog". REQUIRES a handoff document as input — use blog-handoff skill first if none exists. Produces fun, deep, self-deprecating technical posts. --- # Blog Writing ## Overview Write technical blog posts that are fun AND deeply informative. Posts a senior engineer would share in Slack — not because they're polished, but because they're genuinely interesting and honest about the messy process. **REQUIRES**: A `BLOG_HANDOFF.md` generated by the blog-handoff skill. If none exists, invoke blog-handoff first. ## BEFORE WRITING: Interactive Design Phase **You MUST use AskUserQuestion to align before drafting.** Do NOT start writing immediately. ### Round 1: Framing - "The biggest surprise seems to be [X]. Should the post open with that, or build up to it?" - "I'm reading [result/decision] as [interpretation]. Is that how you see it?" ### Round 2: Structure - "I plan to structure as: (a) [opening hook], (b) [version journey], (c) [results reveal]. Reorder?" - "This could be one long post (~15min read) or split into [Part 1: topic] and [Part 2: topic]. Which?" ### Round 3: Tone - "There are some funny friction moments [example]. Lean into humor or keep it straight?" - "How much of the human-AI back-and-forth should I include — just pivots, or also the typos and miscommunication?" ### Round 4+: Draft sections After alignment, draft section by section. After each major section, use AskUserQuestion: - "Here's the opening. Too dramatic? Too dry? Right tone?" - "The V3→V4 transition — I framed it as [X]. Does that capture what actually happened?" ## The Voice **Sound like**: A developer at 2am explaining to a friend why they've been down a rabbit hole for 6 hours — self-aware, technically deep, a little unhinged, genuinely excited about the weird details. **Don't sound like**: A corporate blog, a press release, a tutorial, or an AI-generated summary. **Self-deprecation**: The 🤦 and 😭 emojis are reserved ONLY for genuine self-criticism — "strict F1 of 0.0000 🤦" or "we ran 45,000 samples with the wrong prompt 😭". **No other emojis.** **The author's expletives**: The author swears naturally. Don't sanitize — "NO FUCKING WAY!", "wtf" are part of the voice. Use sparingly but don't censor when the moment calls for it. ## Capturing the Human-AI Dynamic Search the transcript using keywords from the handoff. The friction IS the story. **CRITICAL: This is NOT model bashing.** Both sides mess up. The user sends typos, has half-formed ideas, and sometimes is flat wrong. The model overcomplicate things, misreads intent, and sometimes confidently does the wrong thing. The blog should show BOTH sides honestly — it's a collaboration where two imperfect parties stumble toward a good result. That's what makes it relatable and funny. **From the user side** (user messes up too!): - Typos and half-formed ideas that were hard to parse - Times the user was wrong or changed their mind - When the user's gut instinct turned out right before the data confirmed it - Ideas that took multiple attempts to communicate — sometimes because the idea wasn't clear yet **From the model side** (model messes up too!): - Wrong assumptions, overcomplication, confidently doing the wrong thing - Check compaction summaries — model's internal prioritization shows there - Times the model needed correction and course-changed - When the model added unnecessary complexity the user had to cut **The tone**: Two collaborators roasting each other affectionately, not a user complaining about a tool. ## The Core Principle: Document the Process AND the Reasoning The blog is NOT about results. It's about **how you got there** and **why you made each choice**. How v1 became v2 became v3 became v4 became v5. What broke at each step. What insight drove the next version. The wrong assumptions that seemed right at the time. **CRITICAL: Every major decision must include the reasoning behind it.** Don't just say "we switched to mxbai-embed-large-v1." Explain WHY: - What was the problem with the previous approach? - What alternatives were considered? - What logic led to this specific choice over the alternatives? - What tradeoffs did the choice involve? The reader should be able to follow the chain of reasoning at every pivot point. If the handoff has a Decision Log, use it. If not, reconstruct the reasoning from the transcript. Examples of reasoning that MUST be included: - **Tool choices**: "We used embeddings because manual synonym blacklists don't scale to 3,419 labels, and we used them as a safety filter (exclude synonyms) rather than a selection mechanism (pick hard negatives) because random selection gives a natural difficulty mix." - **Methodology choices**: "We used an LLM judge not to evaluate the NER model, but to validate our own benchmark — to check whether our 'distractors' were actually absent from the text." - **Architecture choices**: "We sent text-only to the encoder because the gline-rs API takes text and labels as separate inputs — the instruction prefix was never part of the designed input format." - **Pivots**: "We dropped from threshold 0.74 to 0.60 because the LLM judge revealed that 58% of our distractors were valid NER types. The cosine filter removed synonyms of gold labels, but didn't remove other valid entity types present in the text." **The "why" is what turns a changelog into a story.** A reader can see WHAT happened from the code. They need the blog to understand WHY it happened. ## Banned Language Never use: - "We're excited/thrilled to announce" - "Best-in-class" / "industry-leading" / "cutting-edge" - "Seamless" / "Empower" / "Leverage" / "Unlock" - "In this blog post, we will explore..." - "Without further ado" / "It's worth noting that" ## Structure ### Opening (2-3 sentences max) State the problem or conclusion. Never start with background. ### The Journey (bulk) Version-by-version. Each section answers: what did we learn from the previous failure? AND why did we choose this specific fix over alternatives? - Exact numbers from outputs (never round) - Code snippets showing key decisions - Comparison tables across versions - The wrong assumptions and when they broke - **The reasoning chain**: problem → alternatives considered → why this solution → what tradeoff we accepted ### Ending Something useful or honest. What works, what doesn't, what's open. ## Technical Standards - **Numbers over adjectives**: exact figures, never "significantly improved" - **Code must be real**: from the actual session - **Tables for comparisons**: mandatory when iterating across versions - **Honesty over hype**: if gold labels are messy, say so ## Headings **Weak**: "Background", "Results", "Conclusion" **Strong**: "71% of the dataset wasn't NER at all", "V5: just pass the damn labels" ## Multi-Post Handling If proposing multiple posts, use AskUserQuestion: - "Part 1 covers [X], ends on [cliffhanger]. Part 2 covers [Y]. Each stands alone. Agree?" - Each post must work independently — no "see Part 1 for context" ## Style Notes - Digressive but purposeful — tangents that loop back - Self-referential humor about own obsessions - Footnotes for asides that break flow - Technical precision mixed with informal tone - Don't force the style — let it emerge from content ## Non-Negotiables - Real person's name on byline - Code that actually ran - Exact numbers from outputs - Acknowledge limitations - If you claim it, show the evidence - When in doubt, go deeper - **REQUIRES handoff document** — don't write from scratch ## See also (related skills — Blog family) If your issue relates to: - **capture session state for a future blog post** — check `blog-handoff` if appropriate.