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
81 lines
4.9 KiB
Markdown
81 lines
4.9 KiB
Markdown
# 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.
|
||
|
||
## 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`](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.
|