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 hentes innholdet og en KB-fil skrives i transformasjonslaget (lag 4, Sesjon 5) — for nå holder det å registrere + flagge for henting.

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 d. Oppdater fila: Edit med relevante endringer. Behold "For Cosmo"-seksjonen og overordnet struktur. Oppdater Last updated: YYYY-MM-DD-header til dagens dato 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.