Engineering Blog Posts skill for Codex

An engineering post works when a practitioner finishes it knowing one thing they did not know before, can trust it because the evidence is on the page, and would send it to a colleague. Readers forgive plain prose; they do not forgive a post with no point.

Pin the post down before drafting

Write these in a scratch file. If you cannot fill a line, ask the user.

Reader:        backend engineers running Postgres at moderate scale
One idea:      partial indexes cut our write amplification by 38% without query regressions
Why now:       we just finished the migration; numbers are fresh
Evidence:      before/after write IOPS graph, two EXPLAIN plans, migration script
What we got wrong: first attempt locked a hot table for 40 s
Call to action: try the audit query on your own schema; we're hiring (optional, one line)
Length target: 1,200-1,800 words

“One idea” is the test. If it takes two sentences, the post is two posts.

Pick the post type

Type	Hook	Spine	Must include
Deep dive / how it works	A surprising behaviour or a question readers have	Mental model, then layers of detail	A diagram; code or config that readers can run
How we built / migrated X	The constraint that made it hard	Problem, options, decision, execution, results	Rejected alternatives and why; real numbers
Performance write-up	The headline number	Baseline, method, change, result, caveats	Method details, hardware, dataset size, reproducibility
Lessons learned / public incident	The impact, stated plainly	What happened, why, what changed	Timeline, contributing factors, no blame, concrete fixes
Feature announcement	The problem it removes	Before, after, how to try it	Working snippet, availability (plans, regions, versions), docs link
Opinion / practice	A claim worth arguing	Claim, evidence, counter-arguments, conclusion	Acknowledge where the advice does not apply

Workflow

- [ ] 1. Fill the scratch block above; confirm reader and one idea with the user if unclear
- [ ] 2. Gather evidence: graphs, numbers, code, PR links, incident docs
- [ ] 3. Outline as 4-7 headings that read as a story when listed alone
- [ ] 4. Draft the body first, then the intro, then the title
- [ ] 5. Cut: remove every paragraph that does not serve the one idea
- [ ] 6. Check claims, code and numbers; run the snippets
- [ ] 7. Pre-publication review (confidentiality list below)
- [ ] 8. Hand back the draft; publishing happens only on the user's explicit go-ahead

Openings

The first two or three sentences decide whether anyone reads on. Start with one of:

• The result: “We cut our CI time from 41 minutes to 9. Most of it came from one change we had dismissed twice.”
• The problem in concrete terms: “Every Monday at 09:00 UTC our queue depth tripled and p99 latency hit 8 seconds.”
• The surprising fact: “Postgres will happily use an index that makes your query slower.”

Avoid: company history, “In today’s fast-paced world”, definitions of well-known terms, “In this post we will…”. If a roadmap sentence is needed, make it one line after the hook.

Body rules

• Headings tell the story: someone reading only the headings gets the arc.
• Show, then explain: put the graph, the log line, the code first; interpret after.
• Numbers carry units, sample sizes and conditions: “p99 dropped from 820 ms to 140 ms over 7 days of production traffic (~2.1k req/s)”.
• Code snippets are minimal, runnable and tagged with a language; link the full repo.
• Include what went wrong and what you would do differently. It is the most valuable and most often cut part.
• Diagrams for any architecture with more than three boxes; alt text on every image.
• Paragraphs of two to four sentences; online readers scan.
• End with a short conclusion that restates the idea in light of the evidence, plus at most one call to action.

Titles

Write five candidates, pick the most specific. Good titles name the thing and the outcome or tension.

Weak	Strong
Improving our CI	How we cut CI from 41 to 9 minutes without new hardware
Thoughts on caching	The cache that made our API slower
Announcing Webhooks v2	Webhooks v2: signed payloads, replay, and 30-day retention

Keep titles under about 70 characters so they survive search results and social cards. For a search-optimised article targeting a query, hand off to $seo-content-writing.

Benchmarks and claims

• State the environment: hardware, versions, dataset size, concurrency, warm or cold.
• Report distributions (p50, p95, p99), not single averages.
• Compare against a fair baseline, configured the way its maintainers recommend.
• Publish the script or methodology when comparing against another product.
• Do not claim causation from one before/after graph when other changes shipped in the same window; say what else changed.

Pre-publication review

Before handing over a draft meant for a public blog, check and flag:

Risk	Look for
Secrets and internals	Hostnames, internal URLs, IPs, account IDs, tokens in screenshots or logs
Customer data	Names, emails, logos, usage numbers of identifiable customers without permission
Security	Details of unpatched vulnerabilities or defences that aid an attacker
Business data	Revenue, headcount, unreleased features, vendor contract terms
Legal and claims	Comparative claims about competitors, performance guarantees, licensing of quoted code
Attribution	Images, diagrams and quotes used without rights or credit

List findings for the user. Company posts usually need sign-off from the owning team and sometimes legal or security review; say so rather than assuming it is cleared.

Publishing, scheduling, or posting to a blog platform or social channel is outward-facing: never do it without the user’s explicit confirmation of the final text and destination.

Gotchas

• A post that is really the internal design doc with “we” replaced by “you”. Rebuild it around the reader’s question.
• Burying the result in the last section. Put the headline number in the first paragraph.
• Ten screenshots of dashboards with no annotation. Crop, annotate, and explain each one.
• Over-hedging every sentence. State the claim once with its conditions.
• Code that only compiles with internal libraries. Replace with public equivalents or pseudocode clearly marked as such.

Verification

• The one-idea sentence appears, in some form, in the first three paragraphs and the conclusion.
• Every number traces to a source (dashboard export, benchmark output, PR) you can name.
• Every snippet was run or is marked as illustrative.
• Reading only the headings conveys the arc.
• Pre-publication checklist completed and findings reported.

Deliverable

**Title:** How we cut CI from 41 to 9 minutes without new hardware
**Alt titles:** 4 others listed below
**Reader / one idea:** platform engineers / test sharding by historical timing beat bigger runners
**Length:** 1,540 words, 2 diagrams (alt text included), 3 snippets (all run)
**Needs sign-off:** build-infra team (owns numbers); legal not needed (no competitor claims)
**Flagged:** screenshot 2 shows an internal hostname, blurred in the draft
**Not done:** publishing (awaiting your go-ahead and target platform)