open/ms-ai-architect
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions
ms-ai-architect/docs/ref-kb-direction-note-2026-06.md
Kjell Tore Guttormsen 6ae0ed5821 docs(ms-ai-architect): reconcile ref-KB named/folder-premiss — 169/220/0 autoritativt 
ref-file-audit.py re-kjørt: reproduserbart 169 navngitt / 220 mappe / 0 orphans.
Workflow-akse-1s 151/238 var et ikke-reproduserbart engangsanslag (strammere
named-heuristikk) — forkastet. Immaterielt: intet tiltak kjører på named/folder-
grensen, kun «0 orphans» (begge enige). Lukker reconcile-flagget i plan + notat.
2026-06-26 10:15:46 +02:00

18 KiB
Raw Permalink Blame History

Provenans Gjelder
Generert av dynamic workflow `ref-kb-analysis` (2026-06-26) — 5 parallelle akse-analyser (Opus 4.8 xhigh) → adversariell kritiker → syntese. Gjennomgått av hovedkontekst. Bygger på `docs/ref-kb-audit-2026-06.md` (verifisert ground truth). Beslutning IKKE tatt — dette er input til operatør. skill-reference-filene (de 389). IKKE Google OKF — OKF er reservert for brukerens egen kontekst/«second brain» (se `docs/okf-second-brain-brief-2026-06.md`).

Beslutningsnotat — Hvordan ms-ai-architect bør lage og oppdatere sine 389 reference-filer

Bunnlinje

Diagnosen er korrekt og delt av alle fem aksene: ingen mekanisme måler i dag om en ref-fils påstander stemmer mot MS Learn — Spor D måler struktur per skill, KB-refresh måler alder per fil. Men «vi måler ikke korrekthet» er ikke det samme som «korrektheten er dårlig»: KB-en scorer 91–96 med 0 stale filer, og base-raten av faktiske feil er aldri målt. Anbefalt førstesteg er derfor ikke å bygge, men å måle: én sesjons stratifisert manuell stikkprøve (~30–40 filer vektet mot volatile påstander) mot live MS Learn fastslår feilraten — og den raten, ikke en antakelse, avgjør om noen av de dyre retningene (LLM-groundedness-judge, frontmatter-migrasjon, registry-herding) er berettiget. Den eneste rene struktur-fiksen som er verdt å gjøre uavhengig av målingen er TOC på de ~20–29 største filene (>800 linjer). Hvis judgen senere bygges, er retningen #2 (eget ref-eval-spor) bygget på #3s substrat (KB-refresh-pipelinen) — aldri #1.

Akse 1 — Struktur og størrelse

Verifisert fakta. Median 481 linjer, snitt 507, 183/389 filer >500 linjer, største 1265 (architecture/adr-template.md). Alle 5 SKILL.md er 169–294 linjer. 384 av 387 filer >100 linjer mangler innholdsfortegnelse (TOC). Eval N4 måler TOC, men med vekt 1 av 23 og uten gulv — nær-total svikt koster ~4 poeng og bryter aldri 90-målet.

Best practice. 500-linjers-regelen gjelder SKILL.md-body, ikke ref-filer; ref-filer har «no context penalty until accessed» og kan bunte omfattende innhold. Men: filer >100 linjer skal ha TOC øverst slik at Claude ser hele omfanget selv ved delvis lesing. Kilde: Anthropic «Skill authoring best practices» (platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices), §Token budgets, §Runtime environment, §Structure longer reference files.

Anbefaling (vurdering). Ikke masseoppdel for størrelsens skyld — store ref-filer er eksplisitt sanksjonert. TOC-løftet er reelt kun for de største filene: under whole-file named-core-routing (agenter leser ~3 hele kjernefiler) er partial-read en uobservert feilmodus, og de ~350 filene på 100–500 linjer leses helt og vinner ingenting. Legg derfor TOC kun på de ~20–29 filene >800 linjer der partial-read faktisk er plausibelt. Kirurgisk splitt av adr-template (flytte 2 av 3 ADR-eksempler ut) gir kun gevinst hvis adr-writer-agent laster malen men ikke trenger eksemplene — et umålt lastemønster; trenger den et eksempel laster den søsterfila, og nettogevinsten er null pluss migrasjonschurn. Utsett. (Merk: adr-template bor i ms-ai-advisor, som er gjenstand for forestående Cosmo-utfasing — se sekvenserings-risiko under.)

Akse 2 — Innhold og korrekthet

Verifisert fakta. Ingen mekanisme leser ref-body semantisk. KB-refresh har per-fil URL-mapping (306/389), per-fil staleness-post og adversariell klassifisering (verify-out: status-gate + refutation + authority-mismatch). Men kun 7/389 filer har streng **Source:**-header, og kun 3 URL-er i registryet har authority_source satt — det utpekte autoritets-ankeret en rigorøs grounding krever eksisterer praktisk talt ikke ennå.

Best practice. Faithfulness/groundedness måles ved å dekomponere output i diskrete påstander og NLI-/entailment-sjekke hver mot kilden (RAGAS Faithfulness — docs.ragas.io). Microsofts egen analog: Azure AI Content Safety Groundedness detection (learn.microsoft.com/azure/ai-services/content-safety/concepts/groundedness). LLM-judge bør ikke skåre hver request med dyr frontier-judge — kombiner billige heuristikker + selektiv sampling + policy-trigget audit, og kalibrer mot et menneske-merket subset først (Langfuse/Confident AI-praksis). Anthropic: «Avoid time-sensitive information» — volatile fakta (GA/preview/versjon/pris) er høyest risiko.

Anbefaling (vurdering). En per-fil groundedness-judge er teknisk riktig formet (per-fil enhet, claim-dekomponering, entailment mot utpekt kilde), MEN tre kritikk-punkter endrer kalkylen vesentlig:

  • Invertert leverage. Alle akser er enige om at de volatile påstandene — nøyaktig de som faktisk råtner — må forbli operatør-gated og aldri auto-scores. Judgen auto-scorer da de stabile, lav-risiko-påstandene og punter de høy-risiko-volatile til mennesket. Frontier-dollar brukes der feil er minst sannsynlig.
  • Kostnaden er feilestimert. «$20–40 via Batch API» er feil: microsoft_docs_fetch er et Claude-i-loop MCP-kall, ikke en Batch-workload. Ærlig kostnad er Akse 4s: per-fil × per-kilde (median 7 kilder/fil) ≈ ~2700 ikke-batchbare, rate-begrensede fetch-kall per full-pass.
  • Den fjerner ikke verifiseringsplikten. Judgen er ikke-deterministisk og claim-dekomponering er erkjent brittle; dens egen output må operatør-kalibreres og revideres. Netto menneske-innsats flyttes fra «stikkprøv KB-en» til «kalibrer + revider judgen» — ROI-premisset er udokumentert.

Konklusjon: judgen bygges kun hvis den målte feilraten (se Bunnlinje) viser en restklasse av reelle feil uten lastmod-endring (feillesning/feildestillasjon) — det er den eneste verdien judgen tilfører over den eksisterende staleness-loopen, og den er aldri tallfestet.

Akse 3 — Hvordan vi måler kvalitet

Verifisert fakta. Spor D (skill-score.mjs) aggregerer per SKILL (5 enheter); K8 sjekker kun at en kilde-/Verified-header finnes (sample-ratio over 5 filer, vekt 1), aldri at innhold stemmer. Begge dashbord er grønne (alle skills ≥90, 0 stale). Scoringsmotoren har allerede gulv-mekanikk (K1/K10 floor:true ⇒ min(rawScore, 89)).

Best practice. Groundedness-evaluator behandler «response» mot «context» med 1–5-skala + terskel→Pass/Fail (Azure RAG-evaluators — learn.microsoft.com/azure/foundry/concepts/evaluation-evaluators/rag-evaluators). Analytisk per-kriterium-scoring avslører hvorfor noe feiler; 3–5 kriterier er sweet spot; krev konkret bevis, ikke vage gradord (G-Eval, Liu et al., EMNLP 2023). Mål konsistens med repetisjoner for ikke-deterministisk judge (learn.microsoft.com/agent-framework/agents/evaluation).

Anbefaling (vurdering). Hvis en innholds-akse bygges: opprett en EGEN, ortogonal akse (Spor E / innholds-troverdighet) per fil, ikke utvid Spor D — #1 er en granularitets-kategorifeil (én råtten fil fortynnes til 96/100 i et skill-snitt over 153 filer). Men kritikken avdekker en reell fare i Akse 3s forslag: et hardt worst-file-gulv på et brittle judge-signal gir alarm-tretthet og waiver-spam — én falsk-positiv gulver hele skillen under 90 og fyrer Spor D-alarmen i SessionStart. Gulv-grammatikk passer deterministiske kriterier (K1/K10), ikke et ikke-deterministisk judge-signal. Hvis aksen bygges, bør judge-gulv være rapporterende (worstFile + countBelow), ikke en hard SessionStart-gate, før judgen er kalibrert. Merk også overlapp: foreslått CT5 (sourcedness) er samme signal som dagens K8 — CT5 bør erstatte K8s rolle, ikke leve parallelt, ellers dobbelttelles og to dashbord kan divergere.

Akse 4 — MS Learn fetch-dekning

Verifisert fakta. Registryet dekker 306/389 filer (78,7 %) med ≥1 pollet kilde-URL; 83 (21,3 %) er helt utenfor (= audit-ens URL-løse filer). 309 siterte URL-er er not_in_sitemap (usynlige for ferskhets-flagget), inkl. hele M365-Copilot-kategorien og 12/17 Agent Framework-lenker. Kobling fil↔kilde er mange:mange (median 7 kilder/fil, maks 21). Pipelinen henter aldri innhold selv — report-changes er ren dato-aritmetikk; fetch + re-verifisering er et separat Claude-i-loop apply-steg på kun flaggede filer, mot ÉN utpekt kilde.

Best practice. sitemap <lastmod> er publisher-kontrollert og ofte upålitelig — en side kan endre innhold uten lastmod-bump (Yoast, yoast.com/lastmod-xml-sitemaps-google-bing). MS Learn eksponerer canonicalUrl + ms.date + updated_at; siteringer bør peke kanonisk og verktøy bør følge redirect. microsoft_docs_fetch gir full sidetekst til grunning (microsoft-learn MCP tool-instruksjoner).

Anbefaling (vurdering). Registry-herding er et reelt, billig og retnings-uavhengig forbedringspunkt: legg graph/ai-builder/power-apps/power-automate/microsoftsearch i sitemap-prefiksene (~25 stack-relevante URL-er reddes), fang skjemaløse siteringer (2 filer der learn.microsoft.com mangler https://), og følg redirect så legacy-stier (44 M365-Copilot-URL-er) re-kanonikaliseres. Dette er en konfig-justering, ikke et program — men det er ikke haster-kritisk så lenge feilraten er umålt. Viktigste innsikt herfra: «fersk» ≠ «korrekt» selv for de 306 dekkede filene (lastmod-only fanger ikke innholdsdrift uten bump) — dette er det reelle argumentet for en korrekthets-sjekk, men det tallfester ikke hvor stor restklassen er.

Akse 5 — Metadata-substrat

Verifisert fakta. 0/389 bruker YAML-frontmatter; alle bruker prosa-header med 34 distinkte nøkler på tre språk (Status ×344, Last updated ×337, Category ×322 + norske varianter). report-changes tolererer allerede 3 dato-mønstre og kjører grønt. Write-pathen er sentralisert i ÉN funksjon (transform.mjs buildKbHeader), og YAML-parser (splitFrontmatter) finnes og er battle-tested for SKILL.md.

Best practice. Anthropic foreskriver ingen metadata for ref-filer (kun SKILL.md krever name+description) — minimalisme er legitimt. Maskinlesbar, konsistent frontmatter er en docs-as-code-standard (Diátaxis; docsio.co). Eksplisitt freshness-dato som maskinlesbart felt (MS Learn ms.date — learn.microsoft.com/contribute/content/metadata). Type-tagging slik at hver fil behandles etter sin art (Diátaxis). Ikke bak inn volatil status i det stabile substratet (Anthropic, §Avoid time-sensitive).

Anbefaling (vurdering). Full YAML-frontmatter på 389 filer (6–8 script + write-path-regresjonsrisiko + dømmekrafts-pass på 81 filer) er over-engineering forbi det ene genuint nyttige feltet. Parsingen er ikke ødelagt — den løser et problem som ikke har feilet. Det verdifulle skillet er type: reference vs template/methodology (redder de 83 kildeløse fra urettferdig korrekthets-straff og gjør manglende kilde på en faktafil maskin-detekterbar). Det skillet trenger ikke YAML — en enkelt tag, mappekonvensjon eller sidecar-manifest gir samme nytte til en brøkdel av kostnaden. Full frontmatter blir først berettiget hvis #2/#3-judgen faktisk skal bygges (da trenger den per-fil source+verified deterministisk) — altså nedstrøms av målingen, ikke før.

Anbefalt retning (#1 / #2 / #3)

Førstevalg: ingen av dem ennå — MÅL feilraten først. Alle fem akser hopper fra «vi måler ikke korrekthet» til «bygg et stående system» uten å fastslå om korrektheten faktisk er ødelagt. Det bryter operatørens egne anti-patterns («starte ambisiøse tiltak når en konfig-justering holder»; «endre X filer når én holder») og er klassisk feilallokering: å bygge en $-per-kjøring-detektor før base-raten av det som skal detekteres er kjent.

Betinget valg, hvis målingen rettferdiggjør bygging: #2 bygget på #3s substrat — aldri #1.

  • #1 forkastes (delt konklusjon, høy konfidens): Spor D scorer per SKILL (5 enheter); korrekthet er per-fil/per-påstand og aggregerer til usynlighet der.
  • #2 som enhet (per-fil korrekthetsdom) på #3s substrat (KB-refresh-pipelinen: microsoft_docs_fetch + url-registry + judge-gating, refresh-kadens — ikke SessionStart). Ren #3 (score på staleness-flagget) bommer på korrekthet-uten-staleness; ren parallell pipeline dupliserer infrastruktur som allerede finnes.

Hva kritikken endret (mot de fem aksenes opprinnelige «bygg nå»):

  • Degraderte hele judge-programmet fra «bygg nå» til «bygg kun hvis målt rate krever det».
  • Avdekket invertert leverage: judgen auto-scorer lav-risiko stabile påstander; de volatile (som faktisk råtner) forblir operatør-gated uansett.
  • Korrigerte kostnaden: ikke batchbar, ~2700 MCP-fetch per full-pass (ikke «$20–40 Batch»).
  • Avslørte at grunnings-ankeret nesten ikke finnes (3 URL-er med authority_source, 7 filer med Source-header) — gjør judgen bak-tung.
  • Reduserte frontmatter til én type-tag (sidecar/konvensjon), ikke full YAML-migrasjon.
  • Reduserte TOC til de ~20–29 største filene, ikke alle 384.
  • Satte adr-template-splitt på vent (betinget av umålt lastemønster + Cosmo-kollisjon).

Billigste høyverdi-grep først (rangert)

  1. Stratifisert manuell stikkprøve mot live MS Learn (~30–40 filer, 1 sesjon, null ny infrastruktur). Vekt mot volatile påstander (Status=Preview, pris/SKU, versjon, GA-datoer) på tvers av alle 5 skills. Noter feilraten. Dette er det manglende inputet som avgjør hele programmet — lav rate (~few %) ⇒ judge ikke berettiget, staleness+stikkprøver holder; høy rate ⇒ evidens-basert begrunnelse og settet dobler som judge-kalibreringssett. Som sidegevinst retter samme pass de få volatile feilene som faktisk finnes — nettopp flaten judgen per design aldri ville auto-scoret.
  2. TOC på de ~20–29 filene >800 linjer. Eneste rene struktur-fiks verdt å gjøre uavhengig av målingen; billig forsikring mot partial-read der den faktisk er plausibel. Skript det for konsistent format.
  3. Registry-herding (konfig-justering). Legg de ~5 manglende sitemap-prefiksene, fang de 2 skjemaløse siteringene, følg redirect for legacy-stier. Retnings-uavhengig; forbedrer ferskhets-dekningen uansett senere valg. Ikke haster-kritisk.
  4. Type-tag for reference vs template/methodology/regulatory (sidecar/konvensjon, ikke full frontmatter). Lavt-kost skille som hindrer at de 83 kildeløse filene straffes urettferdig av en evt. korrekthets-sjekk. Gjør først når #2/#3 er besluttet.
  5. (Betinget på måling) Bygg #2-på-#3-judgen — kun hvis stikkprøven viser en reell feil-restklasse uten lastmod-endring. Forutsetter da: backfill av per-fil autoritets-binding (lag 3), full frontmatter med source+verified, kalibrering mot operatør-merket subset, og rapporterende (ikke hard SessionStart-gate) gulv inntil judgen er kalibrert.

Åpne valg for operatør

  • Bygge judge eller ikke? Avgjøres av stikkprøvens feilrate. Operatøren markerte korrekthets-sporet som viktigst å gjøre skikkelig — form (enhet, substrat, autoritets-backfill-rekkefølge) skal godkjennes FØR bygging, ikke utledes underveis.
  • Sekvenserings-risiko mot Cosmo-utfasing. Cosmo-fjerning er godkjent og «gjøres sist», og treffer ms-ai-advisor — den lavest-scorende skillen (91) og hjemmet til adr-template. Enhver frontmatter-/split-/TOC-jobb på advisor-filer kolliderer med imminent Cosmo-fjerning. Operatør må bestemme: vent med advisor-arbeid til Cosmo er ute, eller koordiner.
  • De 83 kildeløse filene. Hvilke er legitimt kildeløse (maler/metodikk: decision-trees, cost-models) vs. MS-faktapåstander uten sporbar kilde? Krever dømmekraft (Opus-batch), ikke blind skripting. Dette er uansett første steg i en korrekthets-audit.
  • N4-re-vekting. Skal TOC-regelen håndheves reelt (re-vekt N4 eller skaler sub-score med filstørrelse)? Det vil midlertidig dra dagens 91–96 under 90-gulvet og utløse Spor D-alarmer — en policy-beslutning, ikke en defekt, som må kommuniseres som sådan.
  • Frontmatter-omfang. Full YAML-migrasjon (kun berettiget hvis judge bygges) vs. minimal type-tag. category-feltet: fjern (krever refaktor av taxonomy.getCategorySkill til mappesti-utledning) eller behold (redundant mot mappestruktur)?

Verifiseringslogg

Påstand Kilde / ground truth Status
389 ref-filer (advisor 62, engineering 153, governance 78, infra 34, security 62); median 481 / snitt 507 linjer; 183 >500; største 1265 Audit-fakta (filsystem-skann) Verifisert
384/387 filer >100 linjer mangler TOC; N4 vekt 1/23, ikke gulv Audit + skill-score.mjs Verifisert
500-linjers-regel gjelder SKILL.md-body; ref-filer har «no context penalty until accessed»; TOC anbefalt >100 linjer platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices Verifisert (Anthropic)
Spor D scorer per SKILL strukturelt; K8 sjekker header-tilstedeværelse, ikke sannhet; scorer 91–96, 0 stale skill-score.mjs, change-report.json Verifisert
Kun 7/389 filer har **Source:**-header; kun 3 URL-er har authority_source authority.mjs / registry (adversariell kritikk) Verifisert
306/389 filer dekket av ≥1 pollet URL; 83 uten kilde; 309 URL-er not_in_sitemap; median 7 kilder/fil url-registry.json, Akse 4 Verifisert
report-changes er ren lastmod-aritmetikk; fetch er separat Claude-i-loop apply-steg mot ÉN kilde run-weekly-update.mjs, report-changes.mjs, transform-prompt.md Verifisert
Groundedness/faithfulness = dekomponer i påstander + entailment mot kilde RAGAS (docs.ragas.io), Azure Content Safety Groundedness (learn.microsoft.com) Verifisert (WebSearch)
sitemap <lastmod> er upålitelig; innhold kan endres uten bump yoast.com/lastmod-xml-sitemaps-google-bing Verifisert
microsoft_docs_fetch er Claude-i-loop MCP, ikke Batch-API ⇒ ikke −50 %-batchbar microsoft-learn MCP tool-instruksjoner; Akse 4 ~2700 fetch-estimat Verifisert — korrigerer Akse 2s «$20–40 Batch»
Anthropic foreskriver ingen ref-fil-metadata; «avoid time-sensitive information» Anthropic best-practices Verifisert
Base-raten av faktiske korrekthets-feil Ingen — aldri målt IKKE VERIFISERT — dette er det avgjørende manglende inputet
ROI av judge over eksisterende staleness-loop (feil uten lastmod-endring) Ingen tallfesting i noen akse IKKE VERIFISERT
Premiss-avvik: «navngitt 169 / mappe 220» (audit) vs «151 navngitt / 238 mappe-only» (Akse 1) ref-file-audit.py re-kjørt 2026-06-26 → reproduserbart 169/220/0 RECONCILED — 169/220/0 autoritativt; 151/238 (ikke-reproduserbart engangsanslag) forkastet. Immaterielt: intet tiltak kjører på named/folder-grensen, kun «0 orphans» (begge enige)