# Building a knowledge base — the team recipe

> **This is a documented team process, not a wizard.** Setting up a knowledge base for
> portfolio-optimiser is always done by a small team — a technical person and a domain expert
> working together — because the framework side (MAF configuration, bundle structure) is
> genuinely involved. There is deliberately **no onboarding interview and no guided verdict
> command**: both were evaluated and rejected (operator decision D-H,
> [`docs/plan/2026-07-14-revisjonspakke-DF-DI.md`](plan/2026-07-14-revisjonspakke-DF-DI.md) §3).

## The honest expectation

A good knowledge base takes **1-2 weeks of dedicated work**, and the quality of that investment
determines the quality of the result. This is not a limitation to engineer around — it is the
realistic cost of curating a body of knowledge an agent can reason over. Budget for it up front.

> Sourced, not invented: this is verbatim in the operator decision record
> (`docs/plan/2026-07-14-revisjonspakke-DF-DI.md` §3, item 1 — «en god base tar 1–2 uker dedikert
> arbeid — kvaliteten på investeringen avgjør resultatet»).

## Who does what

The team is always **two roles** — never one person, and never a self-service form:

- **The domain expert** contributes subject-matter knowledge. Their interface is deliberately
  minimal: *what* to contribute, *how*, and *where* — nothing more. They deliver **files in their
  own formats** (documents, spreadsheets, notes) — **never schemas or JSON**. What they should
  contribute next is steered by the evaluator's sufficiency feedback ("is this comprehensive
  enough to be useful? what is missing?"), which becomes the expert's worklist during buildup.
- **The technical person** runs the pipeline: builds the OKF bundle, runs ingest and the
  evaluator, and manages the framework configuration.

The verdict is always the human's; the machine only ever translates and structures.

## The process, in phases

1. **Inventory** — the domain expert gathers the source material in whatever formats they already
   have it in. No reformatting into schemas — that is the technical side's job.
2. **Bundle skeleton** — the technical person builds the OKF bundle: `index.md`, the concept
   files, and the cross-links, from the inventoried material.
3. **Seed verdicts** — prior expert judgements are seeded so the first run's hypotheses start from
   what experts actually decided (the ExpeL fold reads them). *See the factory note below: today
   verdicts are authored directly in the strict format; free-format translation is a future
   capability.*
4. **Iterate** — run the evaluator, read its sufficiency feedback, and have the domain expert fill
   the gaps it names. Repeat until the base is comprehensive enough to be useful. This iteration
   loop is where most of the 1-2 weeks is spent.

## Reading the bundle

Bundles are plain markdown, so **Obsidian or VS Code** are enough to read and navigate them — no
dedicated tool is required. (A dedicated reading view is a possible future toolkit building block,
not a prerequisite — per D-H §3 item 5.)

## Future / factory-dependent (not available today)

The following are part of the intended process but depend on the **bundle factory** and the
external toolkit repo, which are not built yet (D-G / T0). They are named here so the recipe stays
honest about what ships today versus what is planned — never claiming above the evidence level:

> - **Free-format verdict translation.** The intended flow: the expert delivers a free-format file
>   and the factory AI-translates it into the strict verdict format (manual translation does not
>   scale to large volumes), with the structured verdict always pointing back to the expert's
>   original file so a spot-check can compare "what the expert wrote" against "what the system
>   understood". Until the factory exists, verdicts are authored directly in the strict format.
> - **Clone-to-demo path.** The intended demo: a fresh clone → drop the example into a bundle
>   inbox → the factory builds it → the whole loop runs. Until the factory exists, use the
>   committed example bundle and the offline simulation
>   (`uv run python -m portfolio_optimiser.simulation`).

Where this recipe is thinner than your situation needs, treat the gap as an open question for the
team to resolve together: the process is deliberately not over-specified beyond the decision record
it is grounded in.