From 1228b35d8124c51039e4311b337c3ecd7e5bfca0 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Fri, 19 Jun 2026 13:29:35 +0200 Subject: [PATCH] =?UTF-8?q?docs(ms-ai-architect):=20kb-update=20brief=20?= =?UTF-8?q?=E2=80=94=20medium/low=20sesjonsplan=20+=20delegerings-metode?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Oppdatert run-brief etter at critical (41b390b) + high (25bcb74) er ferdige: - Status: critical+high FERDIG; medium (~74) + low (~51) PLANLAGT i nye sesjoner. - Ny seksjon «Metode (evidensbasert): DELEGER store bøtter» — dokumenterer det beviste mønsteret fra high-bøtta: grupperte Opus-subagenter (~6 filer/gruppe, delt kilde), subagent-kontrakt (verifiser mot kilde, aldri commit), og hovedkontekst-verifisering etter (git-diff + validate + kb-integrity + gitleaks + single-commit). Erstatter den opprinnelige «main-context»-antakelsen, som ikke skalerer (Learn-sider 50KB+, medium+low = ~268 unike fetches). - Sesjonsplan M (medium) + L (low) med fil-/fetch-/gruppe-estimater. - Antall subagenter ikke en begrensning (operatør-godkjent) — split styres av hovedkontekstens verifiseringslast, ikke agent-antall. - Re-poll FØRST hver sesjon (klassifisering drifter med fil-alder). Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01REiKFhP4w6xGXXqWKpPCJJ --- docs/kb-update-apply-brief.md | 74 +++++++++++++++++++++++------------ 1 file changed, 48 insertions(+), 26 deletions(-) diff --git a/docs/kb-update-apply-brief.md b/docs/kb-update-apply-brief.md index 59a203c..adf76e4 100644 --- a/docs/kb-update-apply-brief.md +++ b/docs/kb-update-apply-brief.md @@ -1,40 +1,62 @@ # 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._ +_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 -**UTSATT — venter på operatør-go. Ikke startet.** Change-detection-fasen er klar; kun apply (fetch + edit + commit) gjenstår. +## Status (2026-06-19) +- **Critical (15) — FERDIG** (`41b390b`, pushet). +- **High (49) — FERDIG** (`25bcb74`, pushet 2026-06-19). +- **Medium (~74) + Low (~51) — PLANLAGT**, ikke startet. Kjøres i nye sesjoner (se sesjonsplan). -## 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. +## 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. -## 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`. +**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 -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). -## 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. +## Sesjonsplan (medium + low) +| Sesjon | Bøtte | ~Filer | ~Unike fetches | ~Grupper (~6/gr) | +|--------|-------|--------|----------------|------------------| +| **M** | medium | ~74 | ~129 | ~13 | +| **L** | low | ~51 | ~139 | ~9 | -## 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. +- **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. -## 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). +## 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. -## 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. +## 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 `Last updated:`-header = kjøredato. -- `git log --oneline` viser refresh-commit(er) med `[skip-docs]`-suffiks. +- 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.