4f076c927d
## M0p1 — Embeddable Runtime Skeleton (329 tests)
- TidalDb with builder(), health_check(), close(), and Drop-based cleanup
- TidalDbBuilder fluent API: ephemeral(), with_data_dir(), wal_dir(), cache_dir()
- Config, StorageMode, ConfigError types; Config(ConfigError) variant on LumenError
- Paths: single source of truth for directory layout (wal, items, users, creators, cache)
- TempTidalHome: test isolation helper gated behind #[cfg(test)] / test-utils feature
- 8 integration tests: tests/sandboxed_storage.rs
## M0p2 — Tooling & Diagnostics (349 tests)
- Workspace root Cargo.toml (members: ["tidal", "tidalctl"])
- tidal/build.rs: BUILD_HASH from GIT_HASH with option_env!() fallback to "dev"
- MetricsState: always-compiled Arc-shared atomics (uptime, health_ok)
- MetricsHandle (metrics feature): hand-rolled TcpListener HTTP, zero new deps
- GET /healthz → {"status":"ok","uptime_secs":N}
- GET /metrics → Prometheus text (tidaldb_uptime_seconds, health_ok, info)
- TidalDbBuilder.enable_metrics(addr) starts background metrics thread
- tidalctl binary: status + paths commands, manual std::env::args() parsing
- 7 metrics integration tests, 9 tidalctl CLI tests
## m1p4 Signal Ledger (in-progress)
- SignalLedger: DashMap<(EntityId, SignalTypeId), EntitySignalEntry>, WAL-first writes
- HotSignalState: #[repr(C, align(64))], lock-free CAS decay, out-of-order handling
- BucketedCounter: 60 per-minute + 168 per-hour circular buffers, trigger-based rotation
- CheckpointMeta + serialize/restore: 983-byte fixed records, atomic WriteBatch
- Property tests: running score matches analytical to 1e-6, decay monotonic, non-negative
- Proptest regression: signals/warm.txt
## Documentation and planning
- ROADMAP: m0p1 COMPLETE (329), m0p2 COMPLETE (349), product track milestones
- PRODUCT_ROADMAP: P0-P4 product milestone track (personal briefing beachhead)
- Milestone planning docs: milestone-0 (phases 1-3), milestone-p (phases 1-5)
- docs/research/tidaldb_tooling_and_diagnostics.md
- ARCHITECTURE.md, CLAUDE.md, VISION.md updates
## Site
- Blog: every-platform-builds-the-same-6-systems.mdx (new)
- Blog: why-tidaldb.mdx (updated)
- next.config.ts, layout.tsx, blog/page.tsx updates
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
186 lines
9.2 KiB
Markdown
186 lines
9.2 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.
|
|
|
|
## Content Strategy Reference
|
|
|
|
**Read `docs/content-strategy.md` before writing any post.** It maps every blog post idea to a specific roadmap phase, names the thesis, identifies the source material, and specifies when the post is ready to publish.
|
|
|
|
The content strategy defines 16-20 posts across the full roadmap. Do not invent posts outside this plan without first checking whether the strategy already covers the topic. If it does, follow the strategy's guidance for that post. If the strategy has a gap, propose adding to it -- do not write an orphan post.
|
|
|
|
### Determining What to Write Now
|
|
|
|
1. Check the **Current Status** section in `docs/planning/ROADMAP.md` to identify which phases are complete
|
|
2. Cross-reference with the **Reference: Roadmap to Post Mapping** table in `docs/content-strategy.md`
|
|
3. The post is ready to write when its roadmap phase has passed UAT and benchmark numbers exist
|
|
4. Exception: Post 1 ("Every content platform builds the same 6 systems from scratch") can be written any time -- it depends on the problem, not the implementation
|
|
|
|
### Current Queue (update as phases complete)
|
|
|
|
As of m1p3 complete, m1p4 next:
|
|
|
|
| Priority | Post | Status |
|
|
|----------|------|--------|
|
|
| 1 | Post 1: "Every content platform builds the same 6 systems from scratch" | Ready -- no code dependency |
|
|
| 2 | Post 3: "What three databases taught us before we wrote a line of code" | Ready -- m1p1-m1p3 complete, thoughts.md is source |
|
|
| 3 | "Why we chose fjall over RocksDB (for now)" | Ready -- m1p3 complete |
|
|
| 4 | Post 2: "Running decay scores are O(1)" | Blocked on m1p4 benchmarks |
|
|
| 5 | Post 4: "Signals wrote 100ms ago. The query sees them now." | Blocked on m1p5 / M1 UAT |
|
|
|
|
## When to Use
|
|
|
|
- After completing a roadmap phase or milestone -- check the content strategy for which post maps to that phase
|
|
- When an architectural decision deserves a public narrative -- check if the strategy already has an ADR planned for it
|
|
- When a benchmark result tells a compelling story -- the strategy specifies which posts need benchmark data
|
|
- When announcing a release, feature, or open-source milestone
|
|
|
|
## Context to Load
|
|
|
|
Before writing, the agent must read -- in this order:
|
|
|
|
1. **`docs/content-strategy.md`** -- find the post in the strategy, read its thesis, source material, and publication criteria
|
|
2. **The source material named in the strategy** -- the specific docs, research files, and task docs listed for that post
|
|
3. **Relevant source files** -- the actual Rust code that was written or changed
|
|
4. **Git log** -- `git log --oneline` for the period covered
|
|
5. **Previous blog posts** -- `site/` blog content directory for voice consistency
|
|
6. **VISION.md** -- for tonal calibration (match its conviction)
|
|
7. **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.
|
|
**Strategy posts:** Post 3 (three databases), Post 7 (ranking profiles), Post 9 (negative signals), Post 12 (Tantivy), Post 16 (graceful degradation), plus the "anytime" ADRs (Why not SQL, Why fjall, USearch not from scratch).
|
|
**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 would watch for (risks, trade-offs acknowledged)
|
|
|
|
**Title pattern:** Thesis statement, not label.
|
|
- "Running decay scores are O(1) -- here is 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.
|
|
**Strategy posts:** Post 4 (M1 complete), Post 5 (M2 complete), Post 13 (M5 complete).
|
|
**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 is 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.
|
|
**Strategy posts:** Post 2 (decay math), Post 6 (diversity), Post 8 (feedback loop), Post 10 (cold start), Post 11 (hybrid search), Post 14 (cohort trending), Post 15 (crash recovery).
|
|
**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"
|
|
|
|
### Vision / Problem Statement
|
|
**When:** Defining the problem space before or independent of implementation.
|
|
**Strategy posts:** Post 1 (the 6-system stack).
|
|
**Structure:**
|
|
1. The problem, made visceral -- name the systems, name the failure modes
|
|
2. Why it exists (historical accident, not intentional design)
|
|
3. The thesis: what should be true instead
|
|
4. The one-query vision (end with the destination, not a product pitch)
|
|
|
|
**Title pattern:** The indictment.
|
|
- "Every content platform builds the same 6 systems from scratch"
|
|
|
|
### 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 is 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 is not self-evident
|
|
|
|
### Audience Calibration
|
|
The reader is an engineer who has built or maintains a recommendation/discovery system. They know what Kafka consumer lag feels like. They know why ranking pipeline cache invalidation bugs never get root-caused. They will recognize the 6-system stack because they operate it. Do not explain what Elasticsearch is. Do not explain what a vector database does. Start from shared pain.
|
|
|
|
### 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. **Check the strategy** -- read `docs/content-strategy.md`, find the post, confirm the phase is complete
|
|
2. **Gather context** -- read the source material listed in the strategy entry for this post
|
|
3. **Find the headline** -- the strategy provides a working title. Sharpen it. If it does not work as a tweet, rewrite it.
|
|
4. **Write the draft** -- narrative first, code second
|
|
5. **Verify code** -- every example must compile and run against the current codebase
|
|
6. **Cut in half** -- remove every sentence that does not earn its place
|
|
7. **Read aloud** -- if you stumble, rewrite
|
|
8. **Write as MDX** -- save to the blog content directory with proper frontmatter
|
|
|
|
## Quality Checks
|
|
|
|
- [ ] Post matches a specific entry in `docs/content-strategy.md`
|
|
- [ ] The roadmap phase for this post is complete (code shipped, not planned)
|
|
- [ ] Title works as a standalone tweet
|
|
- [ ] First paragraph earns the reader's second paragraph
|
|
- [ ] Every code example is correct, copy-pasteable, and from the shipped codebase
|
|
- [ ] Benchmark numbers come from actual `criterion` runs, not estimates
|
|
- [ ] No marketing language ("leverage," "seamless," "robust," "empower," "excited to announce")
|
|
- [ ] 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.
|
|
|
|
## After Publishing
|
|
|
|
1. Update the **Current Queue** table in this skill to reflect the new state
|
|
2. If the post revealed a new insight worth a follow-up, propose adding it to `docs/content-strategy.md`
|
|
3. Do not write the next post until there is something true to say about it
|