3.4 KiB
| id | date | status | supersedes | superseded-by | affected-paths | affected-components | migration_confidence | migration_source |
|---|---|---|---|---|---|---|---|---|
| 0013 | 2026-06-04 | Accepted | medium | 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).