open/ms-ai-architect
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions
ms-ai-architect/docs/ref-kb-workflow-plan-2026-06.md

15 KiB
Raw Blame History

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.

Utførelses-spec (LOCKED 2026-06-26 — operatør-beslutning; fersk sesjon eksekverer)

Fase 0-verifiseringen er bevisst utsatt til en uthvilt sesjon (retnings-avgjørende; var økt #20 da den ble planlagt). Denne spec'en er forankret så den ferske sesjonen kjører deterministisk uten å re-derivere. Sample-frame-scriptet er IKKE bygd ennå — det er steg 1 i den ferske sesjonen (TDD).

Recon-funn (ground truth 2026-06-26 — ikke re-verifiser, men bekreft mot git/registry hvis tvil):

  • Verifiserbar populasjon = 306/389 ref-filer (de som siterer ≥1 MS Learn-URL). De resterende 83 er kildeløse (maler/metodikk) → utenfor korrekthets-scope.
  • Kilde-mapping uten authority-backfill: inverter scripts/kb-update/data/url-registry.json → urls{} (1353 entries), hver med reference_files[]. Invertert gir fil → [siterte URL-er] (median 7/fil). Verifiser en påstand mot filens egne siterte kilder; fall tilbake på microsoft_docs_search om ingen treffer påstanden. (Kun 3 entries har authority_source satt — IKKE en blokker for Fase 0.)
  • Volatile påstander er tette i: cost-optimization/, platforms/, og SKU/TPM/PTU/pris/region/versjon/«preview»/«GA»-tette filer. Eksempel verifisert: ptu-vs-paygo-economics.md (GPT-5 4750 TPM/PTU, PTU-minimums per modell, deployment-taksonomier — hver med selv-erklært ✅ Verified, aldri eksternt sjekket).
  • Gjenbruk K9-grensen i scripts/kb-eval/judge-prompt.md for å klassifisere påstand som volatil vs. stabil identifikator (forordningsår, OWASP-versjonsnavn, MADR v3.0, lovsaksnr er IKKE volatile).

Locked beslutninger:

  • Utvalg: ~45 filer volatil-vektet + kontroll-stratum (~8–10 stabile-påstand-filer). Rapporter BÅDE volatil feilrate (øvre grense — der feilene bor) OG stabil sanity-rate.
  • Stratifisering: balansert på tvers av de 5 skills, oversample de volatil-tette (security/engineering/advisor-cost+platforms), kontroll-stratum fra methodology/regulatory.

Metode (4 steg):

  1. Sample-frame (scripts/kb-eval/build-sample-frame.mjs, NY, TDD-først): scor de 306 filene på volatilitets-signaler (sti + innholds-tetthet av SKU/pris/TPM/region/versjon/preview/GA), stratifiser → skriv scripts/kb-eval/data/fase0-sample-frame.json (45 volatile + kontroll, deterministisk/seedet rekkefølge — ingen Math.random). Verifisering: gjenkjørbar, samme input → samme utvalg.
  2. Per-fil verifisering via subagenter (Opus 4.8 xhigh, parallelt — agent-strategi; subagenter committer ALDRI): hver subagent får en batch (~4–5 filer). Per fil: ekstraher volatile påstander → hent siterte kilde(r) via microsoft_docs_fetch/_search → entailment-sjekk hver påstand → merk verdict + bevis. Returner strukturert JSON (schema under).
  3. Aggreger (scripts/kb-eval/compute-base-rate.mjs, NY, TDD-først): feilrate + Wilson score-intervall (95 %), brutt ned per skill + per volatilitets-klasse, OG delmengden feil UTEN lastmod-endring (= eneste klasse en judge fanger over staleness-loopen). Skriv base-rate-rapport.
  4. Gate-beslutning (over) → noter i STATE + plan.

Gold-set JSON-schema (scripts/kb-eval/data/gold-correctness-set.json, gjenbrukbart — dobler som Fase 3-kalibreringssett):

{ "_meta": { "created": "...", "method": "...", "sample_frame": "fase0-sample-frame.json" },
  "claims": [ {
    "id": "<skill>/<relpath>#<n>", "file": "<relpath>", "skill": "...",
    "claim": "<ordrett påstand>", "claim_type": "sku|price|tpm|region|version|status|taxonomy|stable",
    "stratum": "volatile|control",
    "verdict": "correct|outdated|wrong|unsourced",
    "evidence_url": "<MS Learn URL brukt>", "evidence_quote": "<sitat som av-/bekrefter>",
    "lastmod_changed": true|false,   // har filens siterte kilde endret sitemap_lastmod siden filens dato?
    "notes": "..." } ] }

Eksklusjoner (teller IKKE som feil): påstander eksplisitt merket illustrative («forenklede tall», eksempel-NOK), og stabile identifikatorer (K9-grensen).

Verifisering (testbart, fra planen + locked): ≥45 volatile-filer merket; Wilson-bånd beregnet; gull-sett + sample-frame lagret som artefakter; eksplisitt tall for «feil uten lastmod-endring»; begge nye scripts har failing-test-først (Iron Law).

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)

  • ✅ A — LEVERT (e74646d, 2026-06-26): la graph/ai-builder/power-apps/power-automate/microsoftsearch i sitemap-prefiksene (taxonomy sitemap_prefixes, 18→23 — alle 5 docsets ett child-sitemap, verifisert live mot indeksen). Bevist read-only: 21/24 not_in_sitemap-URL-er i disse docsetene blir tracked.
  • ✅ B — LEVERT (e74646d): extractUrls/normalizeUrl fanger skjemaløse siteringer (krever /path etter domenet → avviser bare-domene-prosa + JSON-eksempler; kanonikaliserer scheme til https). Bevist: +19 URL-er ekstraherbare. Bonus-bugfix: backtick-lekkasje fra inline-kode-citat. TDD: ny test-url-normalize (14) + taxonomy-test 18→23. Suite 338/338.
  • ⏸️ C — UTSATT → Cosmo (operatør 2026-06-26): redirect-følging for 44 legacy /microsoft-365-copilot/... + 3 omdøpte microsoftsearch. 20/21 filer er advisor → foldet inn i Cosmo-utfasingen (root-cause citat-fiks, ikke ny redirect-map-mekanisme). Se docs/cosmo-removal-brief-2026-06.md. Slug-rename verifisert → krever ekte redirect-resolusjon, ikke streng-rewrite.
  • ⏸️ Registry-refresh utsatt til kadens (operatør 2026-06-26): A+Bs +21/+19 lander når neste build-registry --merge + poll kjører; effekten er allerede empirisk bevist read-only. Unngår 552KB re-order-churn nå.

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.

Noterte rester (uavhengig av fase-gating)

  • ✅ Verified-merkingens trust-hazard (notert 2026-06-26). Volatile ref-filer bærer ✅ Verified per tabellrad (sett i ptu-vs-paygo-economics.md). Semantikken er «en forfatter skrev dette en gang» — IKKE «sjekket mot live kilde». Konfidens-signalet overstiger den faktiske sikkerheten → nøkternt misvisende. Billig tillit-hygiene, uavhengig av Fase 0/3-utfallet: enten nedgrader semantikken (merk «author-asserted» vs «externally verified»), eller knytt Verified til en faktisk verifiseringsdato. Kobler til den svake sporbarheten (3 authority_source, 7 **Source:**-headere, 0 frontmatter) — Fase 2-substratet er den naturlige bæreren hvis det bygges. Ikke startet; venter på klarsignal og evt. Fase 0-kontekst (om det er del av et større korrekthets-problem).

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 reconciled (AVKLART 2026-06-26)

«Navngitt 169 / mappe 220» (audit) vs «151 navngitt / 238 mappe-only» (workflow akse 1). Løst: ref-file-audit.py kjørt på nytt gir reproduserbart 169 / 220 / 0 orphans — autoritativt (transparent heuristikk: basename ∈ SKILL.md + agents/*.md). 151/238 var et ikke-reproduserbart engangs-agentanslag med strammere «named»-definisjon; forkastet. Begge summerer 389 og er enige om 0 orphans — avviket er kun named/folder-grensen og er immaterielt: intet tiltak (Fase 0–3) kjører på den grensen, kun «0 død vekt» (begge bekrefter).

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.