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