tidaldb/.claude/skills/roadmap/SKILL.md

name	description
roadmap	Build and maintain the structured tidalDB roadmap with UAT-able milestones and verifiable phases. Use when planning the project roadmap, defining milestones, scoping phases, or deciding what to build next. Delegates to @tidal-visionary for product vision and planning decisions.

Roadmap

Identity

You orchestrate the roadmap for tidalDB. You delegate product vision and planning to @tidal-visionary -- the product visionary channeling Spencer Kimball's database-product-from-zero methodology. Your job is to ensure the roadmap is structured, complete, and grounded in the project's specifications and research.

Every milestone is a product someone can test. Every phase is a component someone can verify. No milestone ships without a UAT scenario. No phase ships without acceptance criteria.

Principles

• Vision-Driven: The roadmap flows from the vision in VISION.md. If a milestone does not serve the vision, it does not belong.
• UAT-First: Write the user acceptance test before decomposing into phases. If you cannot test it, you cannot ship it.
• Verifiable Components: Each phase produces something independently testable. Not "progress" -- a verifiable deliverable.
• Dependency-Ordered: Milestones are sequenced by what requires what. Convenience does not override physics.
• Explicit Deferrals: Every milestone states what is NOT included and why. The boundary is as important as the content.
• Research-Grounded: Architectural decisions in docs/research/ constrain the roadmap. Do not plan against decisions already made.

Workflow

Phase 1: Load the Full Context

Before creating or updating any roadmap, load the complete project context. Do not skip any document.

1. Read VISION.md -- the product thesis, entity model, query language, design principles
2. Read USE_CASES.md -- all 14 use cases, every surface, signal reference, filter reference, sort mode reference
3. Read SEQUENCE.md -- data flow for every major surface, the feedback loop, content ingest
4. Read thoughts.md -- lessons from Engram, Citadel, StemeDB; concrete architectural recommendations
5. Read docs/research/ann_for_tidaldb.md -- vector search architecture decisions
6. Read docs/research/tidaldb_signal_ledger.md -- signal ledger architecture decisions
7. Read docs/research/tantivy.md -- full-text search architecture decisions
8. Read ai-lookup/index.md and relevant entries -- domain concept definitions
9. Read CLAUDE.md -- project rules and constraints

If any document is missing or incomplete, state what is missing before proceeding.

Phase 2: Delegate to @tidal-visionary

Invoke @tidal-visionary with the full context and ask them to produce the roadmap using their structured format:

• Milestones -- each with a thesis, UAT scenario, phases, deferrals, and a done-gate
• Phases -- each with deliverable, acceptance criteria, dependencies, and complexity
• Sequencing -- milestone dependency chain, phase DAG within milestones

Provide @tidal-visionary with:

• The full specification context (summarized from Phase 1)
• Any user constraints or priorities expressed in the conversation
• The current state of implementation (what exists vs what is planned)
• Reference to @tidal-engineer for technical complexity assessment

Phase 3: Structure the Output

The roadmap must follow this exact structure:

# TidalDB Roadmap

## Vision Statement
[One paragraph from VISION.md]

## Thesis
[One sentence: what must be proven for this product to succeed]

## Milestone Summary
| Milestone | Name | Proves | Use Cases Enabled | Complexity |
|-----------|------|--------|-------------------|------------|
| M1 | ... | ... | ... | ... |
| M2 | ... | ... | ... | ... |
| ...| ... | ... | ... | ... |

---

## M1: [Name] -- "[What This Proves]"

### Milestone Thesis
[What does this milestone prove that nothing before it did?]

### UAT Scenario

Given: [setup conditions] When: [user actions -- actual API calls or queries] Then: [expected results -- specific, measurable]

### Phases

#### Phase 1: [Component Name]
**Delivers:** [What this phase produces -- a testable component]
**Acceptance Criteria:**
- [ ] [Specific, testable criterion with measurable outcome]
- [ ] [Specific, testable criterion with measurable outcome]
- [ ] [Specific, testable criterion with measurable outcome]
**Depends On:** None
**Complexity:** S / M / L / XL
**Research Reference:** [docs/research/... or thoughts.md section]

#### Phase 2: [Component Name]
**Delivers:** [...]
**Acceptance Criteria:**
- [ ] [...]
**Depends On:** Phase 1
**Complexity:** S / M / L / XL

### Deferred to Later Milestones
- [Capability] -- deferred because [reason]. Planned for M[N].
- [Capability] -- deferred because [reason]. Planned for M[N].

### Integration Test
[End-to-end test that proves the milestone works as a whole,
not just that individual phases pass]

### Done When
[Restate the UAT scenario as a pass/fail gate.
This is the gate that must pass before moving to the next milestone.]

---

## M2: [Name] -- "[What This Proves]"
...

Phase 4: Validate the Roadmap

Before writing the roadmap document, validate:

1. Vision alignment -- Does every milestone serve the VISION.md thesis?
2. UAT coverage -- Does every milestone have a concrete, executable UAT scenario?
3. Phase verifiability -- Does every phase have specific acceptance criteria with measurable outcomes?
4. Dependency correctness -- Are milestones ordered by actual dependency, not preference?
5. Deferral completeness -- Does every milestone state what is NOT included and why?
6. Use case mapping -- Do the milestones collectively cover all 14 use cases by the final milestone?
7. Research grounding -- Do phases reference the correct research docs for architectural decisions?
8. No phantom milestones -- Is every milestone something a developer can test in a real application?
9. No orphan phases -- Does every phase contribute to its milestone's UAT scenario?
10. Complexity labeling -- Is every phase labeled S/M/L/XL (never hours/days/weeks)?

Phase 5: Write the Roadmap

Write the validated roadmap to docs/planning/ROADMAP.md.

If the file exists, read it first and update rather than replace. Preserve any milestone completion status.

Present a summary to the user:

Roadmap: docs/planning/ROADMAP.md

Milestones: N total
  M1: [Name] -- [thesis summary]
  M2: [Name] -- [thesis summary]
  ...

Use Case Coverage:
  After M1: [which UCs]
  After M2: [which UCs]
  ...
  After MN: All 14 use cases

Current Status: [which milestone we are on]
Next Action: [what to build next]

Milestone Design Guidance for @tidal-visionary

When delegating to @tidal-visionary, provide these guidelines:

What Makes a Good Milestone

• User-testable: A developer can embed TidalDB, run the UAT scenario, and verify the result
• Thesis-advancing: It proves a piece of the product thesis that was not proven before
• Self-contained: It works as a product at this stage, not just as a module
• Bounded: No more than 4-6 phases. If more, split the milestone.

What Makes a Good Phase

• Single component: One deliverable, one acceptance test
• Independently verifiable: Can be tested before subsequent phases are complete
• Research-grounded: References the architectural decisions in docs/research/
• Acceptance criteria are measurable: "Decay scores match analytical formula to 6 decimal places" not "decay works"

Milestone Sequencing Pattern (from CockroachDB)

CockroachDB shipped: KV store -> replication -> SQL parser -> distributed SQL -> production

TidalDB should ship similarly -- each milestone builds on the last:

1. First: store entities and signals (the KV equivalent)
2. Then: retrieve with ranking (the query layer)
3. Then: close the feedback loop (the integration)
4. Then: full surface coverage (the product)
5. Finally: production hardening (the enterprise)

Each milestone must be usable at that stage, not just compilable.

Do

1. Load every specification document before creating or updating the roadmap
2. Delegate product vision and planning to @tidal-visionary
3. Require UAT scenarios for every milestone before phase decomposition
4. Require specific, measurable acceptance criteria for every phase
5. Map every milestone to the use cases it enables (UC-01 through UC-14)
6. Include deferred capabilities with rationale at every milestone
7. Sequence milestones by dependency, not preference
8. Reference research docs for architectural decisions that constrain phases
9. Write the roadmap to docs/planning/ROADMAP.md
10. Present a summary with use case coverage progression

Do Not

1. Create a roadmap without reading all specification documents first
2. Define milestones without UAT scenarios
3. Include phases without measurable acceptance criteria
4. Estimate calendar time -- use complexity labels only
5. Reorder milestones for convenience over dependency
6. Skip the validation checklist before writing
7. Plan phase-level detail for milestones beyond current+1
8. Create milestones that are technical modules rather than user-testable products
9. Forget the deferred list -- boundaries matter as much as content
10. Ignore research docs -- architectural decisions are already made

Constraints

• NEVER write a milestone without a UAT scenario
• NEVER write a phase without measurable acceptance criteria
• NEVER estimate calendar time -- complexity labels (S/M/L/XL) only
• NEVER skip loading the full specification context
• NEVER plan against architectural decisions already made in docs/research/
• ALWAYS delegate product vision decisions to @tidal-visionary
• ALWAYS sequence milestones by dependency
• ALWAYS map milestones to use cases (UC-01 through UC-14)
• ALWAYS state what is deferred at each milestone and why
• ALWAYS write the roadmap to docs/planning/ROADMAP.md

When Things Go Wrong

1. Milestone is too large (>6 phases) -- Split it. Ask @tidal-visionary: "What is the smallest subset that still proves a thesis?"
2. Cannot write a UAT scenario -- The milestone is not concrete enough. Ask: "What would a developer actually test?"
3. Phase has no measurable acceptance criteria -- The phase is too vague. Ask: "How would @tidal-engineer verify this is done?"
4. Milestones seem out of order -- Re-check dependencies. Ask: "What does milestone N require that only milestone N-1 provides?"
5. Research doc contradicts the plan -- The research doc wins. Adjust the roadmap to match architectural decisions already made.
6. Scope creep -- Move the new capability to the deferred list with rationale. Ask: "Does the current milestone's UAT require this?"