Constraints

# Constraints

> When two design goals conflict, the higher tier wins.

## Tier 0 — Existence

1. **Conversation quality must improve with accumulated context.** Day 3 must be meaningfully better than day 1. If it doesn't improve through use, nothing else matters.
2. **The UI is load-bearing, not decorative.** The phase space and context markers are part of the thinking process — not a dashboard bolted onto a chatbot.
3. **Real data, not mocks.** The system must work on actual conversations, not contrived demos.

## Tier 1 — Design Principles

4. **Don't classify. Annotate.** Store traces with minimal metadata. Annotations are computed, re-extractable, and category-free. No predefined types at the schema level — structure emerges from the data.
5. **Immutable traces, improvable annotations.** Raw conversational content is never modified after creation. Everything computed on top (annotations, connections, embeddings) can be recomputed with better models.
6. **Vertical slices over horizontal layers.** Build one thin path through all layers and prove it works end-to-end before widening.
7. **Tests define done.** No component ships without passing tests.

## Tier 2 — Technical

8. **Local-first, zero-cost default.** Every component works without paid APIs. Paid services are upgrades, not requirements.
9. **Single-file database.** One SQLite file. `cp voku.db backup.db` is the backup strategy.
10. **Interfaces over implementations.** Every service has an abstract interface. Swapping providers is a config change.

## Conflict Resolution Examples

*"Should I add predefined annotation types for common patterns?"*
→ Tier 1.4: No. Let types emerge from extraction.

*"Should I use a graph database for connections?"*
→ Tier 2.9: No. SQLite recursive CTEs handle the query patterns at <10K traces.

*"Should the graph be visible during every conversation?"*
→ Tier 0.2: Only on demand. Research shows permanent split-panel hurts conversation quality.