Skip to content

Work / canon / Wiki / Decisions

knowledge-migration

Decisionverified 2026-11-02

Moving knowledge in

Choice: nothing is organized during onboarding, so a company can start in minutes. Four steps: Connect (GitHub organization and repos), Knowledge (Confluence, Notion, Obsidian, Google Drive), Integrate (common tools, or your own by API, MCP or CLI), Pipeline (use the standard one or change it). Then the slow work runs in the background: setup pull requests to merge, and a first sync. Meanwhile a person can customize templates or benchmark repo rules.

  • After the sync: everything is in raw/. Canon distills it into decisions, rules, problems and legacy notes, and checks them against code.
  • No docs: Canon starts from the code, writes what it can read, and asks only what code cannot say.
  • Import: every source page is kept in git with its original link, so nothing is lost.
  • Sort: Canon suggests each page's kind (decision, rule, problem or legacy note) and the repo it belongs in.
  • Verify: each claim gets one result: the code agrees, the code disagrees, no evidence, or out of date.
  • Decide or automate: a person reviews, or lets Canon accept clear results. Conflicts and changes to rules always go to a person.
  • Landing: nothing reaches main without a pull request, one per repo, reviewed in batches. Why: the owner, 2026-11-03: a 15-year-old product with 5 products, 70 teams, 54 repositories, 43 Confluence workspaces and 500 clients must be able to move without losing anything. Old documents are often wrong, and only the code can show which, so copying them unchecked would teach agents old mistakes. See .context/raw/2026-11-03-owner-company-shapes.md. Rejected: organizing products, teams, clients and workspaces during onboarding (the owner, 2026-11-03: it takes hours; Canon suggests structure later, and a copy is at tag archive/onboarding-with-structure) · a first step choosing how to start · copying pages in as they are (agents would trust stale claims) · two-way sync with Confluence (FEAT-0015) · moving everything before a company can start (it should move what matters first) · automation that settles conflicts (a person decides). Now: Confluence import is planned in FEAT-0015. verify: checks a work item against a tool before a stage runs. Checking a page's claims against code does not exist. Open: where raw/ lives before a page is placed in a repo; whether OpenSSF Scorecard, as drawn, is the right benchmark. Revisit: after a test on one real repo, before any build. If results are not good enough to trust, keep import and sort, and let people verify.