tidaldb/.claude/skills/write-blog/skill.md

name	description	agent
write-blog	Write blog posts tracking tidalDB's progress, architectural decisions, and engineering insights. Use when documenting what was built, writing devlogs, announcing milestones, or crafting technical narratives about the database.	tidal-storyteller

Write Blog

Write and publish blog posts for tidalDB using the tidal-storyteller agent.

When to Use

• After completing a roadmap phase or milestone
• When an architectural decision deserves a public narrative
• When a benchmark result tells a compelling story
• For "building in public" devlog entries
• When announcing a release, feature, or open-source milestone

Context to Load

Before writing, the agent must read:

1. Relevant source files — the code that was written or changed
2. Git log — git log --oneline for the period covered
3. Research docs — docs/research/ for technical backing
4. Previous blog posts — maintain voice consistency across posts
5. VISION.md — for tonal calibration (match its conviction)
6. thoughts.md — for the deeper "why" behind architectural patterns

Blog Post Types

Architecture Decision Record (ADR)

When: A major architectural choice was made and the reasoning is worth sharing. Structure:

1. The problem in one sentence
2. What we considered (2-3 options, honestly assessed)
3. What we chose and why — the specific evidence
4. Code showing the result
5. What we'd watch for (risks, trade-offs acknowledged)

Title pattern: Thesis statement, not label.

• "Running decay scores are O(1) — here's the math" not "Signal System Architecture"
• "Why we chose fjall over RocksDB (for now)" not "Storage Engine Decision"

Devlog / Progress Update

When: A phase or milestone was completed. Structure:

1. What we set out to build (the goal, in one sentence)
2. The hardest part (the interesting engineering, not a changelog)
3. What surprised us (the insight the reader takes away)
4. Code showing the key breakthrough
5. What's next (one sentence, not a roadmap dump)

Title pattern: The insight, not the timeframe.

• "10M signals, 4 microseconds" not "Phase 2 Complete"
• "The struct that touches every ranking query" not "February Update"

Technical Deep Dive

When: A specific technique deserves its own focused explanation. Structure:

1. The problem this solves (relatable, concrete)
2. Why the obvious approach fails (with numbers)
3. The technique, explained incrementally with code
4. Benchmarks proving it works
5. Where to learn more (papers, references)

Title pattern: The technique as a claim.

• "Forward decay eliminates 99% of read-time computation" not "How We Handle Decay"
• "Diversity enforcement in 3 microseconds" not "Our Ranking System"

Announcement

When: A release, open-source milestone, or public launch. Structure:

1. What it is (one sentence)
2. What you can do with it (3-5 bullet points with code)
3. Install/quickstart command (prominent, copy-pasteable)
4. What's different about this (the thesis — why this exists)
5. Links: GitHub, docs, community

Writing Standards

Voice

• Active voice. Short sentences. Concrete nouns.
• First person plural ("we") for team decisions, second person ("you") for reader actions
• Technical precision without jargon — say "O(1) per write" not "blazingly fast"
• Humor only when it lands naturally. Never forced.

Structure

• Title is a thesis statement that works as a tweet
• First paragraph earns the second paragraph
• Every paragraph earns the next
• Code blocks show, body text explains
• 800-1500 words for devlogs, 1500-3000 for deep dives

Code Examples

• Must be real — from the actual codebase or a working reproduction
• Must be copy-pasteable
• Include enough context to understand without reading the whole post
• Syntax highlighted with the site's muted dark palette
• Annotated with comments only where the code isn't self-evident

Frontmatter

---
title: "The actual thesis statement"
date: "YYYY-MM-DD"
author: "Name"
description: "One sentence for SEO and social cards"
tags: ["signals", "architecture", "rust"]
---

Workflow

1. Gather context — read source files, git log, research docs, previous posts
2. Find the headline — the one insight worth sharing. Write it as a thesis.
3. Write the draft — narrative first, code second
4. Cut in half — remove every sentence that doesn't earn its place
5. Add code — working examples that show the key insight
6. Read aloud — if you stumble, rewrite
7. Write as MDX — save to the blog content directory with proper frontmatter

Quality Checks

• Title works as a standalone tweet
• First paragraph earns the reader's second paragraph
• Every code example is correct and copy-pasteable
• No marketing language ("leverage," "seamless," "robust," "empower")
• Under 3000 words (deep dives) or 1500 words (devlogs)
• Ends with something the reader remembers tomorrow
• Frontmatter is complete (title, date, author, description, tags)
• Would a CTO forward this to their team? If not, rewrite.