open/ms-ai-architect
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions
ms-ai-architect/docs/kb-update-apply-brief.md
Kjell Tore Guttormsen 1228b35d81 docs(ms-ai-architect): kb-update brief — medium/low sesjonsplan + delegerings-metode 
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) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01REiKFhP4w6xGXXqWKpPCJJ
2026-06-19 13:29:35 +02:00

6.2 KiB
Raw Blame History

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) + Low (~51) — PLANLAGT, ikke startet. Kjøres i nye sesjoner (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.