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).
|