Kjell Tore Guttormsen
9d149b3503
Nytt dokument docs/kunnskapsbase-for-en-kjoring.md (norsk, for fagperson + teknisk person): fire kategorier etter hva de FØLGER (prosjekt / fagområde / organisasjon / bestilling), elleve avgjørelsesspørsmål, innholdstype-tabell (eier, leveringsform, rolle i loopen, hva skjer hvis den mangler), og veglys-eksempelet ende til ende mot den innsjekkede basen. Alt er målt, ikke antatt: type-vokabularet (6 typer i drift; de 4 ikke-reserverte er KONVENSJON, nevnt i ingen spec), metode-filene er tre ulike filer (40/81/98 linjer), og fire live-dry-runs på kopier av veglys-basen — uten validator-input.json rc 1, uten cost-baseline.json rc 0 UTEN MELDING, korrupt baseline rc 1. Ingen artefakt (provenance/outbox) bærer forankret/uforankret; foreslått som kodeendring i dokumentets §7, ikke bygget (Iron Law). Oppskriften (knowledge-base-recipe.md) beholder prosess/roller og lenker hit; README Docs-lista får én rad; dokumentet er klassifisert i _LIVE_DOCS (gaten er fail-closed på uklassifiserte dok). extending.md er utdatert på ett punkt (sier ingen eksempelbase shipper cost-baseline.json) — flagget i §6, ikke rettet her. shared/ urørt. 874 passed / 5 skipped. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XJhpbb4acREp56CaQ5bwXV
4.9 KiB
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§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
- 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.
- Bundle skeleton — the technical person builds the OKF bundle:
index.md, the concept files, and the cross-links, from the inventoried material. - 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.
- 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.
Composing the base for one specific run
This recipe describes the process. It does not say which categories of knowledge a given run
needs, what each content type is for, or what happens when one is missing. That is covered, in
Norwegian for the domain expert and the technical person together, in
kunnskapsbase-for-en-kjoring.md — including a worked road
project from the commission to a base that passes the dry-run check. The two documents are
deliberately disjoint: phases and roles live here, composition lives there.
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.