ms-ai-architect/docs/kb-update-apply-brief.md

Brief — /architect:kb-update apply-kjøring

Run-plan for KB-currency-refresh. Autoritativ kommando-spec: commands/kb-update.md — denne briefen dekker beslutninger, metode og sesjonsplan. Pekt til fra STATE.md.

Status (2026-06-19)

• Critical (15) — FERDIG (41b390b, pushet).
• High (49) — FERDIG (25bcb74, pushet 2026-06-19).
• Medium (74) — FERDIG (070141f, committet 2026-06-19; push parkert utenfor vindu). Kjørt som ÉN sesjon med 15 Opus-subagenter (3 bølger). Hovedkontekst fanget 1 regresjon: subagent overforenklet agentic retrieval GA/preview → rettet mot agentic-retrieval-how-to-migrate. Lærdom: gi subagenter PRESISE binding-fakta, ikke lossy STATE-sammendrag.
• Low (~51) — PLANLAGT, siste bøtte. Kjøres i ny sesjon (se sesjonsplan).

Metode (oppdatert 2026-06-19, evidensbasert): DELEGER store bøtter

Kommando-spec'en (commands/kb-update.md) beskriver fetch+Edit i hovedloopen. For STORE bøtter er det upraktisk: Microsoft Learn-sider er 50KB+ (ikke «noen tusen tokens» som opprinnelig antatt), og medium+low = ~268 unike fetches — umulig i én kontekst. High-bøtta (25bcb74) ble derfor kjørt med grupperte Opus-subagenter, som fungerte svært bra (fanget bl.a. 3 reelle faktafeil). Bruk dette mønsteret for medium+low.

Bevist mønster:

1. Re-poll FØRST (dry-run): node scripts/kb-update/run-weekly-update.mjs --force → fersk bøtte-klassifisering. ALLTID re-poll — klassifisering drifter med fil-alder; ikke gjenbruk gammel change-report.json.
2. Hent full fil→endrede-URLer-mapping fra scripts/kb-update/data/change-report.json (filtrer på priority).
3. Grupper filene i bunter på ~6 filer som deler kilder (hver unik URL hentes én gang per gruppe → minimer fetches).
4. Spawn én Opus-subagent per gruppe (Agent, subagent_type: claude, model: opus), med disjunkte fil-sett (ingen skrivekonflikt → ingen worktree nødvendig). Hver subagent: Read → microsoft_docs_fetch (store sider persisteres til fil → Read den fila) → kirurgisk Edit → bump dato → kjøredato (behold filas eksisterende dato-label/format; footer Sist oppdatert→kjøredato, Neste review→+3 mnd hvis de finnes).
5. Subagent-kontrakt (kritisk): verifiser hver faktapåstand mot kilde; fiks motsigelser til å matche kilden; ALDRI oppfinn — flagg uverifiserbart eksplisitt; behold «For Cosmo»/«For arkitekten»-seksjon + struktur; ALDRI git/commit/stage; rør KUN tildelte filer; returner kompakt per-fil-changelog + FLAGS-linje.
6. Gi subagentene de binding-verifiserte faktaene fra STATE.md (relevant utvalg per gruppe) → unngå re-verifisering + motsigelse.
7. Hovedkontekst verifiserer ETTER (subagentenes egenrapport er ikke nok — fila er fasit):
   • git diff --stat → scope = KUN forventede filer, ingen streifende.
   • git-diff-review av de største/mest faktatunge gruppene; spot-sjekk små.
   • alle endrede filer har dato-header = kjøredato (regex-tips: dato-label kan ha kolon inni fet skrift, **Dato:**).
   • validate-plugin.sh (239) · test-kb-integrity.sh (115/115, orphans ≤ 262) · gitleaks.
   • single-commit per bøtte: chore(ms-ai-architect): refresh KB <bøtte>-bucket — N files [skip-docs] (følg 41b390b/25bcb74-stil + Co-Authored-By/Claude-Session-trailers).
   • push (vindu-sjekk: TZ=Europe/Oslo date '+%u %H:%M'; hverdag 20:00–23:00, helg/helligdag fritt — ELLER eksplisitt operatør-go).

Sesjonsplan (medium + low)

Sesjon	Bøtte	~Filer	~Unike fetches	~Grupper (~6/gr)
M	medium	~74	~129	~13
L	low	~51	~139	~9

• Anbefalt: to sesjoner (M først, så L).
• Antall subagenter er IKKE en begrensning (operatør-godkjent «så mange som trengs», 2026-06-19) — subagentene absorberer fetch-lasten, så bruk én per ~6-fil-gruppe (~13 for M, ~9 for L). Sesjons-splitten styres av hovedkontekstens verifiseringslast (diff-review av N filer), ikke agent-antall. M+L kan teoretisk gjøres i én sesjon, men 2 anbefales for grundig diff-review. Splitt Medium til M1/M2 (~37 hver) kun hvis verifiseringen blir for tung.
• Hver sesjon: ÉN bøtte (--priorities medium hhv. --priorities low), --single-commit.
• Discovery: historisk kun Databricks-støy (2 kjøringer på rad) → --skip-discover anbefalt for fart; operatør avgjør ved kjøring.
• Low har lite kilde-gjenbruk (139 unike for 51 filer) → grupperingen sparer få fetches der, men holder fortsatt subagent-kontekst ren.

Per-sesjon oppstart (kort sjekkliste)

1. Fersk sesjon i ms-ai-architect/. claude mcp list → bekreft microsoft-learn aktiv.
2. git status rent + på main i synk (kommandoen blander inn ucommittede .md).
3. Re-poll: node scripts/kb-update/run-weekly-update.mjs --force (--discover kun hvis ønsket).
4. node scripts/kb-update/report-changes.mjs | head -40 → bekreft bøtte-tall (kan ha driftet siden 2026-06-19).
5. Hent fil→URL-mapping → grupper → spawn Opus-subagenter → verifiser (punkt 7 over) → single-commit → push → oppdater STATE.md.

Etter kjøring — obligatorisk

• Telling-resync: apply på EKSISTERENDE filer endrer IKKE 389. KUN hvis discovery legger til NYE skills/-filer må 389 re-synkes overalt: README badge + prosa + KB-tabell + per-skill-seksjon; CLAUDE.md skill-tabell; SKILL.md subdir-tabell. Nye filer MÅ wires i respektiv SKILL.md (ellers orphan-warnings > 262). Fasit: find skills/*/references -name '*.md' -type f | wc -l.
• STATE.md: oppdater ved sesjonsslutt (fjern fullført bøtte; oppdater HEAD/push-status).

Fallgruver

• Sitemap-coverage ~69 %: ~31 % (mest azure/ai-foundry/openai/) finnes ikke pga. URL-restrukturering → rapporteres «always stale», vurderes manuelt.
• MCP-tilgjengelighet: krever aktiv microsoft-learn-server.
• Modellvalg: Opus for diff-nyanse (subagentene settes eksplisitt til model: opus).
• Regex på dato-header: **Dato:**/**Sist oppdatert:** har kolon inni fet skrift — match på selve dato-strengen, ikke **Label**.

Verifisering (testbare kriterier)

• bash tests/validate-plugin.sh → 239 PASS / 0 FAIL.
• bash tests/test-kb-integrity.sh → 115/115; orphan-warnings IKKE økt utover 262 (med mindre nye filer bevisst lagt til + wiret).
• Hver oppdatert fil har dato-header = kjøredato.
• git log --oneline viser refresh-commit med [skip-docs]-suffiks.
• Hvis discovery kjørte: README/CLAUDE.md/SKILL.md-tellinger matcher faktisk filtelling.