413b712c0a
- Schema phase 1 (tasks 01-02): EntityId, EntityKind, Timestamp, Score, SignalTypeDef, DecayModel, Window, WindowSet — all with property tests and benchmarks scaffolding - Stub modules for storage, signals, query, ranking - Full documentation suite: VISION, USE_CASES, SEQUENCE, API, CODING_GUIDELINES, ai-lookup, research docs, specs, roadmap, planning docs - Marketing site (Next.js) with blog infrastructure - .claude/ agents and skills for the tidalDB development workflow - Foundation standards enforced: thiserror + tracing declared as dependencies, clippy::unwrap_used = deny added to lint config - .gitignore hardened: .next/, node_modules/, .env, secrets, logs Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
132 lines
5.1 KiB
Markdown
132 lines
5.1 KiB
Markdown
---
|
|
name: write-blog
|
|
description: 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.
|
|
agent: 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
|
|
```yaml
|
|
---
|
|
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.
|