---
name: writing-blog-posts
description: Writes technical blog posts built on one specific claim, a three-sentence hook, and real code, numbers, and failures. Use when the user asks to write a blog post, an engineering blog article, a technical write-up of a project or incident, or a dev.to/Medium-style post. Do not use for documentation, tutorials, or marketing landing-page copy — separate skills cover those.
---

<!--
Author: Simon-Pierre Boucher
Contact: contact@spboucher.ai
-->

# Writing Blog Posts

## When to use / when NOT to use
- **Use for:** technical blog posts, engineering write-ups, postmortem narratives for a public audience, "how we built X" articles.
- **Do NOT use for:** documentation (writing-technical-documentation), tutorials (writing-tutorials), API reference (writing-api-documentation), or landing-page copy (frontend-skills/creating-landing-pages).

## House rules

1. **One idea per post, stated as a specific claim in the title.**
   - ✅ "We cut our CI bill 60% by deleting half our integration tests"
   - ❌ "Thoughts on testing"

2. **Hook in the first 3 sentences** — the problem, a surprising fact, or the result. No throat-clearing.
   - ✅ "Our CI bill hit $40k/month. The fix wasn't caching or bigger runners — it was deleting 4,000 tests. Here's how we decided which ones."
   - ❌ "Testing is a very important topic in software engineering. In this post, I will share some thoughts…"

3. **Real code, real numbers, real failures.** Specifics earn trust; sanitize secrets, keep the mess.
   - ✅ "The first attempt shaved 4% — nowhere near worth the two weeks it took."
   - ❌ "After some optimization, performance improved significantly."

4. **Subheadings tell the story alone.** A skimmer reading only headings gets the arc.
   - ✅ "The $40k bill → What the tests actually covered → Deleting with a safety net → Results after 90 days"
   - ❌ "Introduction → Background → Discussion → Conclusion"

5. **Personal experience over generic advice.** "We did X and Y happened" beats "you should X".
   - ✅ "We tried contract tests first; they caught 2 of the 17 regressions."
   - ❌ "Consider using contract tests, which can catch regressions."

6. **Honest limitations section** — where this wouldn't work, what you'd do differently.
   - ✅ "This only worked because our unit coverage was already strong; with flaky units, deleting integration tests would be reckless."
   - ❌ Presenting the approach as universal.

7. **At most one call-to-action**, at the end.
   - ✅ One "we're hiring" or one "try the tool" link.
   - ❌ Newsletter box, three product links, and a webinar pitch mid-article.

## Workflow

1. Write the claim as one sentence; if it needs "and", split into two posts.
2. Collect the evidence: numbers, code snippets, timelines, failed attempts. No evidence → no post yet.
3. Outline as story-telling subheadings (rule 4); check the headings alone carry the arc.
4. Draft: hook first (rule 2), then the story, then limitations, then the single CTA.
5. Self-review pass: delete every sentence that could appear unchanged in anyone else's post on the topic; verify every number has a source; confirm exactly one CTA. Fix and re-check.

## Edge cases
- **No hard numbers available** → use concrete qualitative specifics (timeline, error messages, before/after code); never invent or round up.
- **Company-sensitive details** → replace absolute revenue-like numbers with ratios/percentages, and say you did.
- **Post is really a tutorial in disguise** (reader follows steps) → switch to writing-tutorials.

## References
Extended before/after examples: see [references/examples.md](references/examples.md).