Kjell Tore Guttormsen
d44305cda9
New English docs/knowledge-base-recipe.md grounded strictly in the D-H decision record (revisjonspakke-DF-DI.md §3): setup is always a small team (technical + domain expert), the deliverable is a recipe NOT a wizard (B9 onboarding interview + guided verdict command rejected), domain expert delivers files in their own formats never schema/JSON, phased process (inventory -> skeleton -> seed verdicts -> iterate), reading via Obsidian/VS Code. The honest 1-2 week expectation is stated early and SOURCED verbatim to the record. Factory-dependent parts (free-format verdict translation, clone-to-demo) are explicitly marked future/blocked-on-toolkit so the doc never claims above the evidence level. Linked from README's Docs section with the 1-2 week expectation in context. SC5 (ASCII-only greps): file exists, '1-2 weeks' x2, 'knowledge-base-recipe' in README. src/ untouched; 431 passed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KNNiJRk1sSwxgVLS5AobT1
72 lines
4.4 KiB
Markdown
72 lines
4.4 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.
|
||
|
||
## 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.
|