From d98cce371ac63a42be5bff8c403bb4d651cbbcd8 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Fri, 26 Jun 2026 01:02:15 +0200 Subject: [PATCH] docs(ms-ai-architect): gjennomtenkt plan for ref-fil-kvalitet + workflow (Fase 0-4, gated) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fase 0 (gull-testsett/base-rate) gater korrekthets-bygging; Fase 1 trygge grep (registry-herding + TOC + generator-anti-regresjon); Fase 2 minimal type-tag; Fase 3 #2-på-#3-judge betinget; Fase 4 integrasjon. OKF-brief: full pakke for second brain + følg standarden (operatør-direktiv). --- docs/okf-second-brain-brief-2026-06.md | 3 +- docs/ref-kb-workflow-plan-2026-06.md | 86 ++++++++++++++++++++++++++ 2 files changed, 88 insertions(+), 1 deletion(-) create mode 100644 docs/ref-kb-workflow-plan-2026-06.md diff --git a/docs/okf-second-brain-brief-2026-06.md b/docs/okf-second-brain-brief-2026-06.md index ca9ac4a..61a6f10 100644 --- a/docs/okf-second-brain-brief-2026-06.md +++ b/docs/okf-second-brain-brief-2026-06.md @@ -2,8 +2,9 @@ _Notert 2026-06-26. Fremtidig initiativ — IKKE implementer før operatør sier fra. Bygger på research av GoogleCloudPlatform/knowledge-catalog (spec + samples + toolbox). State-of-play i `STATE.md`._ -## Scope-grense (ufravikelig, operatør-bekreftet 2026-06-26) +## Scope-grense + ambisjon (ufravikelig, operatør-bekreftet 2026-06-26) - **OKF gjelder KUN brukerens egen kontekst/data** — hans person- og organisasjonsspesifikke «second brain» / LLM-wiki (i dag onboarding-output i `~/.claude/ms-ai-architect/org/*.md`). +- **For dette sporet kjøres FULL Google OKF-pakke** (ikke bare lån av mønstre): frontmatter-kontrakt + `index.md`-progressiv-disclosure + retrieval + vedlikeholds-/enrichment-mekanisme, modellert på `samples/` + `toolbox/`. **Og adopsjonen holdes oppdatert etter hvert som OKF-standarden utvikler seg** (v0.1 → senere versjoner; fang `okf_version`-bump). Operatør-direktiv 2026-06-26. - **OKF gjelder IKKE de 389 skill-reference-filene.** De forblir Claude Code skill-references (native mekanisme, Anthropic-anbefalt flat/progressiv-disclosure-struktur). Begrunnelse: se `docs/ref-kb-direction-note-2026-06.md` + rekonsidererings-konklusjon i memory `okf-scope-second-brain-only`. ## Hvorfor OKF passer second brain (men ikke skill-refs) diff --git a/docs/ref-kb-workflow-plan-2026-06.md b/docs/ref-kb-workflow-plan-2026-06.md new file mode 100644 index 0000000..8dcd66c --- /dev/null +++ b/docs/ref-kb-workflow-plan-2026-06.md @@ -0,0 +1,86 @@ +# Plan — Reference-fil-kvalitet + hele workflowen rundt den (de 389 skill-refs) + +_Opprettet 2026-06-26. Dette er KJERNEN i ms-ai-architect: innholdet i skills' reference-filer + maskineriet som lager og oppdaterer dem. Kvalitetsbar: svært høy. Operatør-rettesnor: «brukerverdi > teknologi; oppdateringsmekanismene må fungere veldig bra; ta god tid; faktabasert.» Grunnlag: `docs/ref-kb-audit-2026-06.md` (verifisert ground truth), `docs/ref-kb-direction-note-2026-06.md` (workflow-analyse + adversariell kritikk)._ + +## Avgjorte premisser (ikke re-litiger — bekreftet 2026-06-26) +1. **De 389 forblir Claude Code skill-references.** Skills-vs-OKF-bake-off for MS Learn-kunnskapen er DREPT som kaninhull — Anthropic-best-practice ER den flate skill-ref-strukturen; ingen indikasjon på at OKF slår skills. Begrunnelse: direction-note + [[okf-scope-second-brain-only]]. +2. **OKF gjelder kun brukerens «second brain»** (eget spor, senere — `docs/okf-second-brain-brief-2026-06.md`). +3. **#1 (utvid Spor D med korrekthets-kriterium) er forkastet** — kategorifeil (Spor D scorer per skill; korrekthet er per-fil/per-påstand). +4. **Struktur er allerede sunn** (skills 91–96, 0 stale). Det umålte er INNHOLDS-korrekthet. Derfor: ikke masseoppdel filer; store on-demand-filer er Anthropic-sanksjonert. + +## Mål (suksesskriterium — måles mot brukerverdi, ikke teknologi) +Reference-innholdet er **korrekt + ferskt + godt strukturert**, og create-/update-workflowen holder det slik **pålitelig og automatisk**. Konkret: (a) en bruker som chatter får korrekte, oppdaterte MS-svar; (b) oppdateringsmekanismen fanger reell drift, ikke bare lastmod-bump; (c) nye ref-filer fødes best-practice-konforme (workflowen regresserer ikke). + +--- + +## Fase 0 — Gull-testsett + base-rate-måling (FUNDAMENT — gater Fase 3) +**Hvorfor først:** alle fem analyse-akser hoppet fra «vi måler ikke korrekthet» til «bygg system» uten å vite om korrektheten faktisk er dårlig. KB scorer 91–96 med 0 stale — null bevis for et korrekthets-problem, kun fravær av bevis. Å bygge en $-per-kjøring-detektor før base-raten er kjent er feilallokering. + +**Gjør:** +- Trekk et **stort nok, stratifisert** utvalg ref-filer/påstander (start ~30–40 filer; vurder utvidelse), **vektet mot volatile påstander** (pris/SKU, GA/preview, versjoner, regioner) på tvers av alle 5 skills. +- Verifiser hver manuelt mot **live MS Learn** (microsoft_docs_fetch/search). Merk per påstand: korrekt / utdatert / feil / ikke-kildegrunnet. +- Persister som **gjenbrukbart gull-sett** (det dobler som evaluerings-harness for en evt. bake-off + judge-kalibreringssett). + +**Verifisering (testbart):** +- ≥30 filer merket, feilrate beregnet med usikkerhetsbånd; gull-settet lagret som artefakt (f.eks. `scripts/kb-eval/data/gold-correctness-set.json`). +- Eksplisitt funn: hvor mange feil finnes UTEN lastmod-endring (= den eneste klassen en judge fanger over eksisterende staleness-loop). + +**Beslutnings-gate ut av Fase 0:** +- Lav feilrate (~few %) ⇒ judge IKKE berettiget; staleness + periodisk stikkprøve holder. Hopp over Fase 3. +- Høy feilrate ⇒ evidensbasert grunnlag for Fase 3; gull-settet er allerede kalibreringssettet. + +--- + +## Fase 1 — Trygge, retnings-uavhengige grep (kan kjøres parallelt med Fase 0) +Lav risiko, forbedrer workflowen uansett senere valg. **NB: koordiner advisor-filer mot Cosmo-utfasing** (samme skill — se gating-valg). + +### 1a. Update-mekanisme: registry-herding (operatørs prioritet) +- Legg `graph`/`ai-builder`/`power-apps`/`power-automate`/`microsoftsearch` i sitemap-prefiksene (`poll-sitemaps` TARGET_PREFIXES) → ~25 stack-relevante URL-er reddes fra `not_in_sitemap`. +- La `extractUrls`/`url-normalize` fange skjemaløse siteringer (2 filer: `apim-ai-gateway-overview.md`, `ai-governance-structure-framework.md`). +- La `normalizeUrl`/poll **følge redirect** så 44 legacy `/microsoft-365-copilot/...`-URL-er re-kanonikaliseres mot `/microsoft-365/copilot/...`. +- **Verifisering:** `url-registry` tracked-andel stiger; Agent Framework tracked-rate > 5/17; `report-changes` dekker flere filer. Kjør `report-changes.mjs` før/etter. + +### 1b. Create/struktur: TOC på de største filene +- Legg innholdsfortegnelse i de **~20–29 filene >800 linjer** (ikke alle 384 — partial-read er kun plausibelt på de største under whole-file-routing). Skript for konsistent TOC-format. +- **Verifisering:** `eval.mjs checkN4 hasToc` = true for de filene; ingen diff-churn på små filer. + +### 1c. Create-time: hindre regresjon i generatoren +- Oppdater `scripts/kb-update/lib/transform.mjs buildKbHeader`/`validateKbFile` (og evt. `generate-skills`) så NYE/regenererte filer fødes best-practice-konforme (TOC hvis stor; konsistent header). **MÅ gjøres før/sammen med 1b**, ellers regenererer neste KB-update prosa-headere og reverserer arbeidet (write-path-regresjon). +- **Verifisering:** kjør generatoren på en testfil; output har TOC + kanonisk header. + +--- + +## Fase 2 — Metadata-substrat (minimal; full versjon betinget av Fase 3) +- **Minimal type-tag** for hver fil: `reference` | `template` | `methodology` | `regulatory`. Formål: skille de 83 «kildeløse» legitimt (maler/metodikk som `decision-trees`, `cost-models` skal ALDRI ha MS-kilde) fra MS-faktapåstander-uten-kilde (maskin-detekterbart defekt). Kan være sidecar-manifest eller mappekonvensjon — IKKE full YAML-frontmatter ennå. +- **Full frontmatter** (`type`/`source`/`verified`, OKF-kompatibel form) bygges KUN hvis Fase 3-judgen skal bygges (da trenger den per-fil `source`+`verified` deterministisk). Over-engineering ellers — `report-changes` tolererer alt 3 dato-mønstre i dag. +- **Verifisering:** hver av 389 filer klassifisert; de 83 kildeløse delt i to bøtter; judge (hvis bygd) skipper `template`/`methodology`. + +--- + +## Fase 3 — Korrekthets-mekanisme (GATED av Fase 0; bygg kun hvis berettiget) +**Retning (hvis bygd): #2 som enhet (per-fil korrekthetsdom) på #3s substrat (KB-refresh-pipelinen) — aldri #1.** +- Per-fil groundedness-judge (Opus 4.8 xhigh): hent filens utpekte autoritet → `microsoft_docs_fetch` → dekomponer i påstander → entailment-sjekk hver mot kilden (RAGAS/Azure Groundedness-mønster) → score = supported/total + liste over ugrunnede/motstridende påstander. Persister analogt til `skill-score-report.json`, men per fil, med «sist verifisert korrekt»-stempel. +- **Forutsetninger før bygging:** (a) autoritets-backfill — kun 3 URL-er har `authority_source`, 7 filer har `**Source:**`-header i dag; (b) full frontmatter (Fase 2); (c) kalibrer judgen mot Fase 0-gull-settet før tallene stoles på (judge claim-dekomponering er brittle — verifiseringsplikt). +- **«Bygg begge og mål»** (operatørs metodikk) er tilgjengelig her: staleness-flagg vs judge vs hybrid, målt på gull-settet — men **kun på den volatile populasjonen** (der feilene bor; ikke kår en vinner på stabile påstander). +- **Kjente feller (fra kritikk):** invertert leverage (judgen auto-scorer stabile lav-risiko-påstander; volatile forblir operatør-gated); kostnad er ~2700 ikke-batchbare `microsoft_docs_fetch` per full-pass (IKKE «$20–40 Batch»); judgen fjerner ikke verifiseringsplikten (flytter den fra «stikkprøv KB» til «kalibrer judge»). +- **Verifisering:** judge presisjon/recall mot gull-settet ≥ avtalt terskel; staleness-gated inkrement + periodisk full-pass; volatile påstander forblir operatør-gated. + +--- + +## Fase 4 — Integrasjon & styring +- Fold valgt mekanisme inn i KB-refresh-kadens (ikke SessionStart — for dyrt). Spor D viser en tynn PEKER til innholds-scoren, ikke et sammenslått tall. CT5 (sourcedness) ERSTATTER K8s rolle (ikke parallelt). +- Judge-gulv skal være **rapporterende** (worstFile + countBelow), ikke en hard SessionStart-gate, før judgen er kalibrert — ellers alarm-tretthet/waiver-spam på et brittle signal. +- **Verifisering:** SessionStart-hook surfacer innholds-signal uten falske regresjons-alarmer; operatør-waiver-sti finnes. + +--- + +## Gating-valg for operatør (avklares før relevante faser) +1. **Mål-først (anbefalt) vs bygg-begge-direkte.** Begge krever gull-settet (Fase 0) først. +2. **Cosmo-sekvensering.** Struktur-/tag-arbeid på `ms-ai-advisor` (lavest score 91 + hjem til `adr-template`) kolliderer med godkjent Cosmo-utfasing (samme skill). Vente til Cosmo er ute, eller koordinere? Påvirker Fase 1b/1c/2 for advisor-filer. +3. **N4-revekting.** Håndheve TOC-regelen reelt (re-vekt N4 / skaler med filstørrelse)? Drar 91–96 midlertidig under 90 → Spor D-alarm. Policy, ikke defekt. + +## Premiss å reconcile før tiltak +«Navngitt 169 / mappe 220» (audit) vs «151 navngitt / 238 mappe-only» (workflow akse 1). To målinger spriker — reconciler FØR tiltak som bygger på tallene. Endrer ikke retning, men er en åpen ground-truth-uenighet. + +## Anbefalt inngangspunkt (neste sesjon) +**Fase 0 (gull-testsett + base-rate)** er den tunge, retnings-avgjørende jobben og bør gjøres uthvilt — den avgjør om Fase 3 i det hele tatt skal bygges. **Fase 1a (registry-herding) + 1b/1c (TOC + generator)** er trygt håndverk som kan gjøres uavhengig. Velg: start med Fase 0 (avgjør retning), eller ta Fase 1 trygge grep først. Begge tjener kjernen.