57 lines
3.4 KiB
Markdown
57 lines
3.4 KiB
Markdown
---
|
||
id: "0013"
|
||
date: 2026-06-04
|
||
status: Accepted
|
||
supersedes:
|
||
superseded-by:
|
||
affected-paths: []
|
||
affected-components: []
|
||
migration_confidence: medium
|
||
migration_source: "docs/memory-system/03-architecture-decisions.md### ADR-013 — Build-first / migrate-incrementally (build-order inversion)"
|
||
---
|
||
|
||
# 0013 — Build-first / migrate-incrementally (build-order inversion)
|
||
|
||
## Context
|
||
|
||
The build runbook (`05-implementation-process.md`) originally front-loaded bulk
|
||
vault migration as Step 1 — migrating all ~20 existing SecondBrain notes and all projects to
|
||
the ADR-011 six-facet taxonomy before the system existed to validate them. This committed to
|
||
a schema and workflow (the tag taxonomy from ADR-011, the vault-reuse choice from ADR-012,
|
||
and Graphify extraction behavior) before any end-to-end path had been exercised. The risk:
|
||
locking in an approach that fails at scale, with no feedback loop until the entire vault has
|
||
been touched.
|
||
|
||
## Decision
|
||
|
||
**Invert the build order.** The full system is built and validated against a
|
||
small **5–10 note fixture set** first. Bulk vault migration is deferred to the final stage.
|
||
The first real-data validation uses **one small project that contains both code AND
|
||
documents**, exercising both the local-SLM doc-extraction path and the tree-sitter code path
|
||
in the same run. After that single project validates end-to-end, remaining projects are
|
||
onboarded **one at a time** with an observe-and-adjust step between each.
|
||
- **Rationale**: Validates the ADR-011 taxonomy and ADR-012 vault conventions against the real
|
||
Graphify extraction pipeline before the entire vault is committed. The first mixed code+docs
|
||
project surfaces both extraction paths (SLM for docs, tree-sitter for code) early, when
|
||
corrections are cheap. Per-project rollout keeps the blast radius of any schema or workflow
|
||
correction small; each project is an opportunity to observe and adjust rather than discover
|
||
problems across 20 notes at once. This is consistent with the "markdown-as-truth, indexes are
|
||
disposable" principle (ADR-008): the vault notes are durable, but the extraction schema should
|
||
be validated before it shapes all of them.
|
||
|
||
## Consequences
|
||
|
||
The build order was inverted so the full system is validated against a small 5-10 note fixture set first, with bulk vault migration deferred to the final stage; the first real-data validation uses one project mixing code and docs, then remaining projects are onboarded one at a time with an observe-and-adjust step between each. This reduces the blast radius of any taxonomy or workflow correction compared to migrating the whole vault before validating the pipeline.
|
||
|
||
## Alternatives rejected
|
||
|
||
- **Keep migration-first (status quo)**: Front-loads all ~20 notes and all projects before
|
||
any end-to-end validation exists. Commits to ADR-011's taxonomy and ADR-012's migration
|
||
steps against the full vault without a feedback loop — exactly the gap this decision closes.
|
||
- **Big-bang migrate everything after build**: Build against fixtures, then migrate all notes
|
||
and all projects in one batch at the end. Avoids the pre-build commitment problem but still
|
||
risks a single large irreversible migration with no observe-and-adjust loop between units.
|
||
Per-project rollout with intermediate checkpoints is strictly safer.
|
||
- **Cross-references**: ADR-011 (six-facet tag taxonomy — the schema being validated);
|
||
ADR-012 (SecondBrain vault reuse — the migration steps this order defers).
|