ms-ai-architect/commands/kb-update.md

name	description	argument-hint	allowed-tools	model
architect:kb-update	Manuell oppdatering av kunnskapsbasen — poller Microsoft Learn-sitemaps, sammenligner mot lokale `Last updated`-headere, oppdaterer endrede filer og oppdager nye relevante URLer	[valgfritt: --skip-discover | --priorities critical,high,medium,low | --dry-run]	Bash, Read, Edit, Write, Glob, Grep, mcp__microsoft-learn__microsoft_docs_search, mcp__microsoft-learn__microsoft_docs_fetch, mcp__microsoft-learn__microsoft_code_sample_search	opus

/architect:kb-update — Manuell KB-oppdatering

Holder Microsoft AI-kunnskapsbasen i skills/*/references/ ferskt ved å sammenligne lokale referansefiler mot Microsoft Learn-sitemaps. All kjøring er manuell — pluginen schedulerer ingenting, og brukere som ønsker periodisk kjøring sørger for det selv (cron, launchd, GitHub Actions, etc.).

Hva kommandoen gjør

1. Polle sitemaps: kjører node scripts/kb-update/run-weekly-update.mjs --force for å hente fersk <lastmod> for hver Microsoft Learn-URL i registeret
2. Optional discovery: med default --discover finner nye relevante URLer i sitemap som ikke er i registeret (scripts/kb-update/discover-new-urls.mjs --limit 500). Discovery leser beslutnings-ledgeren (data/decisions.json, lag 2) og utelater alt operatøren allerede har tatt stilling til (policy A: approved/rejected/pending) — så de samme kandidatene drukner ikke gaten kjøring etter kjøring
3. Generere endringsrapport: report-changes.mjs produserer data/change-report.json med per-fil prioritering (critical/high/medium/low) basert på antall endrede kilder + alder på lokal fil
4. Vise rapporten: lese rapport, presentere oppsummering til bruker, vente på go
5. Oppdatere filer: for hver fil i valgt prioritetsbøtte (default: critical + high):
   • Hente fersk innhold fra alle endrede kildene via microsoft_docs_fetch
   • Oppdatere relevante seksjoner i den lokale .md-fila
   • Oppdatere Last updated:-header til dagens dato
6. Committe: én git-commit per fil med chore(ms-ai-architect): refresh KB <fil> [skip-docs]-format (eller én samlet commit om brukeren foretrekker det)

Argumenter

Flagg	Effekt
--skip-discover	Hopp over discovery-passet (raskere, ingen nye URLer oppdages)
--priorities <list>	Komma-separert subset av critical,high,medium,low. Default: critical,high
--dry-run	Generer rapport, men ikke oppdater filer eller committ
--single-commit	Samle alle filendringer i én commit i stedet for én per fil

Instruksjoner til assistenten

1. Pre-flight

• pwd — bekreft at du står i plugins/ms-ai-architect/ (eller delegere via absolutt sti)
• git status --porcelain | grep -E '\.md$' && echo "WARN: ucommittede skill-endringer — kommandoen vil blande dem inn" — advar bruker hvis det finnes lokale skill-endringer
• Parse argumenter

2. Kjør pollingsfasen

node scripts/kb-update/run-weekly-update.mjs --force${ARG_DISCOVER}

Hvor ${ARG_DISCOVER} er --discover med mindre --skip-discover ble gitt.

Output forventes å skrive data/change-report.json og evt. nye registry-entries hvis discovery kjørte.

3. Vis rapport-oppsummering

node scripts/kb-update/report-changes.mjs | head -40

Presenter til bruker:

• Antall filer per prioritet
• Hvilke prioriteter som blir behandlet (default: critical + high)
• Estimert antall microsoft_docs_fetch-kall (≈ sum av endrede kilder per fil)
• Spør: "Fortsett med oppdatering? (y/n)"

Hvis --dry-run: stopp her, ikke oppdater filer.

3b. Discovery-gate — nye URLer via decision-ledger (lag 2)

Kjørte discovery (default), lukk løkken her. Dette er operatør-gaten — det eneste stedet beslutninger om nye URLer skrives.

a. Les kandidatene: data/discovery-report.json → candidates[]. Listen er allerede dedupet av scriptet mot både registry og data/decisions.json, så alt her er genuint ubesluttet. Feltet deduped_by_ledger viser hvor mange tidligere beslutninger som ble utelatt.

b. Presenter for operatør, gruppert per suggested_skill (vis url, suggested_category, lastmod). For hver kandidat (eller batch): approve (ta inn i KB), reject (irrelevant — ikke vis igjen), eller utsett (pending — ikke avgjort, vises i pending-bøtta men re-foreslås ikke).

c. Skriv beslutningene til ledgeren — ENESTE skrivevei. Bruk lib/decisions-io.mjs (ikke håndskriv JSON):

import { loadDecisions, recordDecision, saveDecisions } from './scripts/kb-update/lib/decisions-io.mjs';
let led = loadDecisions();
led = recordDecision(led, url, { status: 'rejected', decided_at: '<i dag>', suggested_skill, suggested_category, note });
// ...én recordDecision per beslutning...
saveDecisions(led);

decided_at settes til dagens dato (caller-injisert — recordDecision er ren). decisions.json er tracket i git (overlever, til forskjell fra de genererte rapportene).

d. For approved: registrér URLen i url-registry (gated) så den fanges av polling heretter — via lib/registry-io.mjs saveRegistry. Bruk suggested_skill/suggested_category fra kandidaten. Deretter kjør transformasjonslaget (lag 4) for å lage KB-fila:

1. microsoft_docs_fetch på den godkjente URLen → kildedokument.
2. Destillér via scripts/kb-update/transform-prompt.md (doc→KB-fil; status-påstander holdes eksplisitte). Multi-agent parallell fan-out foreslås i produksjon (roadmap §71), speilet på generate-skills-mønsteret.
3. content = buildKbHeader({title, status, category, source: <godkjent URL>, lastUpdated: <YYYY-MM>}) + body (lib/transform.mjs). Status + Source er obligatoriske — Source i header-blokka (øverste 500 bytes) er det som lar lag 3 backfille authority_source.
4. validateKbFile(content) MÅ være valid: true før noe gates videre (ellers be modellen fylle manglende felt).
5. For hver status-/load-bearing-påstand: buildChange({...}) → lag 5 classifyChange(...) (samme gate som §4 c2). Status-påstander er alltid flagged.
6. resolveTargetPath(tax, category, filename) → eierskill-sti via taksonomien (null = ukjent kategori → flagg for operatør, ikke skriv).
7. Først etter operatør-gate: atomisk skriving (lib/atomic-write.mjs + lib/backup.mjs). transform.mjs skriver aldri selv — verifisert av tests/kb-update/test-transform.test.mjs (import-invariant). Kriterium verifisert av tests/kb-eval/test-transform-criterion.test.mjs (regenerer 1 fil → eval ≥ baseline).

e. Invariant: discover-new-urls.mjs (deteksjon) skriver aldri ledgeren — den kun leser. Bare denne gaten skriver. Verifisert av tests/kb-update/test-discover-invariant.test.mjs.

4. Per-fil oppdatering (etter brukerens y)

For hver fil i valgte prioriteter:

a. Les nåværende fil: Read på filstien b. Hent oppdaterte kilder: for hver URL i change-report.json[file].changed_urls, kjør microsoft_docs_fetch på URLen c. Identifiser endringer: sammenlign hentet markdown mot eksisterende seksjoner i fila. Fokuser på faktuelle endringer (ny info, oppdaterte features, deprecation-varsler) — ikke små formuleringsendringer c1. Autoritetskilde-binding (lag 3) — header-as-truth. authority_source = resolveAuthority(<fil-innhold>) (lib/authority.mjs) — fila sin **Source:**-header ER den utpekte autoriteten for dens påstander. null hvis fila mangler headeren (vokser etter hvert som lag 4 regenererer filer). Dette er inngangsdataen til lag-5 regel 3 (autoritets-mismatch): er en status-/load-bearing-endrings source_url ≠ authority_source, flagges den. Aldri gjett en autoritet fra fila sine siterte URLer (251/303 filer siterer 4–10 → ville vært gjetning). c2. Verifisering-ut (lag 5) — FØR du skriver. Hver kandidat-endring fra (c) går gjennom lib/verify-out.mjs classifyChange({field, old_value, new_value, source_url, authority_source, refutations}) med authority_source fra (c1). Dette fanger regresjons-klassen (en status-påstand «korrigert» mot en tilfeldig sitert side og stille auto-applyet — agentic-retrieval-regresjonen):

• flagged → IKKE auto-skriv. Vis endringen til operatør med reasons[]; operatør avgjør om den tas inn. Status-påstander (GA/preview/versjon/pris) er ALLTID flagged (spec §21) — uansett hvor sikker kilden ser ut.
• auto-applied → trygt å ta inn i (d) (benign, ikke-status, ingen motbevis, autoritets-match).
• Adversarial motbevis-panel (LLM-runtime): for status-/load-bearing-påstander, kjør et lite panel som prøver å motbevise new_value mot den utpekte authority_source, og mat resultatene inn som refutations[] ([{refuted, reason}]). Multi-agent foreslås når lag 4/5 kjøres i produksjon (roadmap §71).
• Invariant: verify-out.mjs skriver aldri — den returnerer kun en verdict. Selve skrivingen skjer i (d), gated. Verifisert av tests/kb-update/test-verify-out.test.mjs. d. Oppdater fila: Edit med endringer som er auto-applied eller eksplisitt godkjent av operatør i (c2). Behold "For Cosmo"-seksjonen og overordnet struktur. Oppdater Last updated: YYYY-MM-DD-header til dagens dato. Lag-4-kontrakt: kjør validateKbFile(<ny fil-innhold>) (lib/transform.mjs) før skriving — den skal være valid: true. Mangler fila et **Source:**-header, legg det til i header-blokka med den utpekte autoritets-URLen for hovedkilden — da fanger lag 3 (resolveAuthority + build-registry) den som authority_source, og lag-5 regel 3 blir virksom for fila. e. Committ: git add <fil> + git commit -m "chore(ms-ai-architect): refresh KB $(basename <fil>) [skip-docs]" med mindre --single-commit ble gitt

5. Single-commit modus

Hvis --single-commit: skip committer per fil, og lag én samlet commit til slutt:

git add skills/
git commit -m "chore(ms-ai-architect): refresh KB — N files [skip-docs]"

6. Push (om bruker bekrefter)

Spør: "Push til Forgejo origin/main? (y/n)". Per global push-policy er direkte main-push pre-autorisert, men spør likevel her siden dette er en bulk-operasjon.

git push origin main

7. Oppsummering

Rapporter:

• Antall filer oppdatert per prioritet
• Antall commits laget
• Hvis discovery kjørte: antall nye URLer oppdaget og lagt til registry
• Eventuelle filer som ble hoppet over (f.eks. ingen reelle endringer i hentet innhold)
• data/change-report.json blir værende på disk for diagnose

Fallgruver

• Sitemap-coverage: ~69% av URLene matche mot sitemap. ~31% (mest azure/ai-foundry/openai/) finnes ikke pga. URL-restrukturering på Microsofts side. Disse rapporteres som "always stale" og må vurderes manuelt
• Microsoft_docs_fetch latency: hver fetch tar 2-5 sek. 9 critical + 44 high filer × ~1.5 kilder hver = ~80 fetches = ~3-7 minutter
• Modellvalg: Opus brukes fordi diff-resonnering + tekst-syntese krever nyanse. For enklere "just refresh dates"-oppdateringer er Sonnet tilstrekkelig — bruker kan overstyre med eksplisitt --model claude-sonnet-4-6 i Claude Code config
• MCP-tilgjengelighet: kommandoen krever at microsoft-learn MCP-serveren er aktiv. Sjekk med claude mcp list ved første kjøring

Når kjøre

• Anbefalt: ukentlig eller månedlig, avhengig av hvor sensitive prosjektene dine er for KB-ferskhet
• Før viktig vurdering: kjør med --priorities critical,high,medium før en stor /architect:utredning eller /architect:adr
• Etter Microsoft-events: Build, Ignite, eller annen større Microsoft-konferanse → forvent mange endringer

Schedulering

Pluginen schedulerer ingenting. Hvis du vil ha periodisk kjøring, sett opp en cron-jobb / launchd-jobb / systemd timer / GitHub Actions-workflow som kjører node scripts/kb-update/run-weekly-update.mjs --force --discover (uten apply-fasen) og varsler deg om å kjøre /architect:kb-update i en interaktiv Claude Code-sesjon.

Apply-fasen (oppdatere filer + committe) kan ikke automatiseres innenfor denne pluginen — den krever LLM-resonnering på endringene og menneskelig vurdering, og er bevisst designet for kjøring fra en åpen Claude Code-sesjon.