diff --git a/docs/kb-update-apply-brief.md b/docs/kb-update-apply-brief.md new file mode 100644 index 0000000..59a203c --- /dev/null +++ b/docs/kb-update-apply-brief.md @@ -0,0 +1,40 @@ +# Brief — `/architect:kb-update` apply-kjøring + +_Run-plan for den ENESTE gjenstående posten etter v1.16.0 (audit #5–#9 komplett). Autoritativ spec: `commands/kb-update.md` — denne briefen dekker kun beslutninger og kontekst spesifikt for DENNE kjøringen. Pekt til fra STATE.md._ + +## Status +**UTSATT — venter på operatør-go. Ikke startet.** Change-detection-fasen er klar; kun apply (fetch + edit + commit) gjenstår. + +## Hvorfor egen, fersk sesjon (besluttet 2026-06-18) +`/architect:kb-update` kjører **alt i hovedkonteksten — ingen subagent-isolasjon** (`microsoft_docs_fetch` + `Edit` i main loop, steg 4b–4d i kommandoen). Default `critical,high` ≈ **53 filer** (9 critical + 44 high) × ~1,5 kilder = **~80 fetches**, hver en full Learn-markdown-side (flere tusen tokens) som akkumuleres i konteksten. Kommandoen bruker Opus fordi diff-resonneringen krever nyanse → best kvalitet med fullt, rent budsjett. Start derfor i fersk sesjon; SessionStart-hooken surfacer denne posten umiddelbart via STATE.md. + +## Anbefalt kjøring +1. Fersk sesjon i `ms-ai-architect/`. +2. `claude mcp list` → bekreft at `microsoft-learn` MCP er aktiv (kommandoen krever den). +3. `/architect:kb-update --dry-run` FØRST → se eksakt fil-/fetch-tall per prioritet før du forplikter. +4. Vurder beslutningspunktene under, kjør så uten `--dry-run`. + +## Beslutningspunkter (operatør avgjør ved kjøring) +- **Prioriteter:** default `critical,high` (~53 filer). Utvid til `--priorities critical,high,medium` kun før en stor utredning/ADR (tyngre, flere fetches). +- **Commit-modus:** `--single-commit` anbefales for ren historikk (én `chore: refresh KB — N files`) framfor ~53 per-fil-commits. +- **Discovery:** default `--discover` på. `--skip-discover` = raskere, ingen nye URLer oppdages. + +## Push-vindu + timing +Apply tar reelt 15–40 min (fetch ~3–7 min + LLM-diff per fil). Hverdager stenger push-vinduet 23:00 → starter du sent, parkér committen til neste vindu (helg åpent). `TZ=Europe/Oslo date '+%u %H:%M'` før push. + +## Etter kjøring — obligatoriske oppgaver +- **Telling-resync:** apply på EKSISTERENDE filer endrer IKKE 389. MEN hvis discovery fører til nye KB-filer, må 389 re-synkes på ALLE steder: README badge (L11) + prosa (L207, L605) + KB-tabell (L214) + per-skill-seksjon (L229); CLAUDE.md skill-tabell (L75); SKILL.md subdir-tabell. Fasit: `find skills/*/references -name '*.md' -type f | wc -l`. +- **Wiring:** nye filer MÅ wires i respektiv SKILL.md (ellers nye orphan-warnings over baseline 262). +- **STATE.md:** oppdater ved sesjonsslutt (fjern kb-update fra gjenstående hvis fullført). + +## Fallgruver (fra `commands/kb-update.md`) +- **Sitemap-coverage ~69 %:** ~31 % (mest `azure/ai-foundry/openai/`) finnes ikke pga. URL-restrukturering hos Microsoft → rapporteres «always stale», vurderes manuelt. +- **MCP-tilgjengelighet:** krever aktiv `microsoft-learn`-server (sjekk steg 2). +- **Modellvalg:** Opus for diff-nyanse; ren «refresh dates» kan kjøres på Sonnet via config-override. + +## 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 `Last updated:`-header = kjøredato. +- `git log --oneline` viser refresh-commit(er) med `[skip-docs]`-suffiks. +- Hvis discovery kjørte: README/CLAUDE.md/SKILL.md-tellinger matcher faktisk filtelling.