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.