Kjell Tore Guttormsen
6ae0ed5821
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.
125 lines
18 KiB
Markdown
125 lines
18 KiB
Markdown
---
|
||
Provenans: 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.
|
||
Gjelder: 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) |
|