reconcile

Reconcile

A change landed: the code moved, but the OKF bundle (knowledge/) may not have. Reconcile them — bring durable knowledge back into agreement with what was actually built, so the next session starts from a consistent bundle.

This is the writing discipline of the build phase — the mirror of /domain-modeling, which writes the bundle during design. It runs last in the /implement closeout, over the same diff /vet judged, so code and knowledge land in one commit.

Scope

Reconcile against the diff, never the whole bundle. Fixed point is the one /vet used, or one the user supplies: git diff <fixed-point>...HEAD.

Durable knowledge is everything under knowledge/ — the canonical categories glossary/, adr/, and spec/, plus any project-specific concept category registered in knowledge/index.md. Touch a concept only when the diff gives you a reason to.

Process

Reconcile runs in two phases: a sub-agent analyses the diff and applies the mechanical fixes, then the main context does the judgement writes. The split keeps the heavy bundle-searching out of the main context — as /vet does — while leaving the consequential writes where the implementation reasoning lives.

Phase 1 — Analysis (sub-agent)

First write a build-rationale brief for the sub-agent — this is what keeps its classification from being blind. Keep it to a few hundred words:

• Pointers, not copies — the spec/issue reference and the commit list (git log <fixed-point>..HEAD --oneline). The sub-agent reads these itself; don't paste them.
• The unwritten "why" — a short synthesis of the non-obvious decisions made while implementing: the "chose X over Y because…" that lives in no file. This is the only input the sub-agent cannot obtain on its own, and the thing its judgement of unrecorded/violated decisions depends on.

Then spawn one general-purpose sub-agent, passing it: the diff command git diff <fixed-point>...HEAD, the brief, and the Classes table below. Its brief: