spb/ultra-sharp-agent-skills Public

1<!--2Author: Simon-Pierre Boucher3Contact: contact@spboucher.ai4-->56# Examples — Blog Post House Style78## Contents9- Complete worked example: opening (bad → house style)10- Title pairs11- Subheading arcs12- Limitations sections13- Gotchas1415## Complete worked example: opening1617**❌ Before:**1819```markdown20# Some Thoughts on Database Migrations2122Database migrations are one of the most important yet often overlooked23aspects of modern software development. Every developer will eventually24need to deal with them. In today's fast-paced world, it's crucial to have25a robust migration strategy. In this post, I will share some thoughts and26best practices that I have learned over the years.27```2829(Four sentences in: no claim, no evidence, nothing the reader can't predict.)3031**✅ After (house style):**3233```markdown34# A 40-character migration took our API down for 11 minutes3536The migration was one line: `ALTER TABLE orders ADD COLUMN note text`.37It locked 90 million rows on our primary at 14:02 on a Tuesday.38This post reconstructs the incident minute by minute, and shows the39expand-migrate-contract pattern we now enforce in CI so it can't recur.4041## 14:02 — the deploy that looked harmless42...43```4445What changed: title is a specific claim with numbers; hook is the problem +46the surprise in three sentences; timeline promises evidence, not opinions.4748## Title pairs4950- ✅ "Keyset pagination made our deep pages 200× faster" / ❌ "Pagination best practices"51- ✅ "We replaced 14 microservices with a monolith and cut p99 by half" / ❌ "Microservices vs monoliths"52- ✅ "Everything we learned fuzzing our YAML parser for 30 days" / ❌ "An introduction to fuzzing"5354## Subheading arcs5556✅ Story alone in headings:5758```59The bill nobody questioned60What 4,000 integration tests actually tested61The deletion protocol: score, quarantine, delete62What broke (two things) and what didn't (everything else)6390 days later: numbers64Where this would have gone wrong65```6667❌ Template headings: `Introduction / Background / Approach / Results /68Conclusion` — interchangeable with any post ever written.6970## Limitations sections7172✅ "This worked because (1) unit coverage was 85%+ before we started,73(2) our services share one language, so contract drift is rare, and74(3) we could tolerate a staging-only canary for two weeks. Team with a75polyglot stack or thin unit coverage: the quarantine step alone is still76worth stealing; the mass deletion is not."7778❌ "Of course, your mileage may vary." (says nothing)7980## Hook patterns (three that work)8182- **The problem:** "Our CI bill hit $40k/month and nobody could say why."83- **The surprising fact:** "Deleting tests made our deploys safer. Here's84  the data."85- **The result:** "p99 went from 840 ms to 210 ms with a one-line change —86  after three weeks of wrong turns. The wrong turns are the useful part."8788All three commit to specifics in sentence one; none begin with the topic's89importance.9091## Gotchas9293- **The generic-sentence test is brutal but works:** if a sentence could94  close any post on the topic ("testing is a journey, not a destination"),95  it adds nothing — delete it.96- **Rounded-up numbers get called out** in comments ("60%" that's really97  48% costs all credibility); use the real figure.98- **Burying the result** to build suspense loses skimmers; the hook may99  reveal the ending — the story is *how*, not *whether*.100- **Code screenshots** aren't searchable or copyable; always fenced blocks.101- **Two ideas in one post** each get half the depth; the split versions102  both outperform the original.103