open/ms-ai-architect
1
0
Fork 0
Code Issues Pull requests Releases Activity
ms-ai-architect/docs/okf-second-brain-brief-2026-06.md
Kjell Tore Guttormsen d98cce371a docs(ms-ai-architect): gjennomtenkt plan for ref-fil-kvalitet + workflow (Fase 0-4, gated) 
Fase 0 (gull-testsett/base-rate) gater korrekthets-bygging; Fase 1 trygge grep
(registry-herding + TOC + generator-anti-regresjon); Fase 2 minimal type-tag;
Fase 3 #2-på-#3-judge betinget; Fase 4 integrasjon. OKF-brief: full pakke for
second brain + følg standarden (operatør-direktiv).
2026-06-26 01:02:15 +02:00

7.5 KiB
Raw Blame History

Brief — Google OKF for brukerens «second brain» (LLM-wiki), IKKE for skill-refs

Notert 2026-06-26. Fremtidig initiativ — IKKE implementer før operatør sier fra. Bygger på research av GoogleCloudPlatform/knowledge-catalog (spec + samples + toolbox). State-of-play i STATE.md.

Scope-grense + ambisjon (ufravikelig, operatør-bekreftet 2026-06-26)

  • OKF gjelder KUN brukerens egen kontekst/data — hans person- og organisasjonsspesifikke «second brain» / LLM-wiki (i dag onboarding-output i ~/.claude/ms-ai-architect/org/*.md).
  • For dette sporet kjøres FULL Google OKF-pakke (ikke bare lån av mønstre): frontmatter-kontrakt + index.md-progressiv-disclosure + retrieval + vedlikeholds-/enrichment-mekanisme, modellert på samples/ + toolbox/. Og adopsjonen holdes oppdatert etter hvert som OKF-standarden utvikler seg (v0.1 → senere versjoner; fang okf_version-bump). Operatør-direktiv 2026-06-26.
  • OKF gjelder IKKE de 389 skill-reference-filene. De forblir Claude Code skill-references (native mekanisme, Anthropic-anbefalt flat/progressiv-disclosure-struktur). Begrunnelse: se docs/ref-kb-direction-note-2026-06.md + rekonsidererings-konklusjon i memory okf-scope-second-brain-only.

Hvorfor OKF passer second brain (men ikke skill-refs)

Avgjørende skille er ikke «er det en LLM-wiki» (begge er det) — men «finnes det allerede en native, anbefalt mekanisme?»:

  • Skill-refs: JA — Claude Code skills + references + progressiv disclosure, allerede Anthropic-best-practice (flat, ett nivå dypt, store filer lastet on-demand, SKILL.md-hub + domene-mapper + grep). OKF ville erstattet et fungerende native system med et ekvivalent fremmed (OKFs retrieval-verdi over skills ≈ null; Grep/Glob/Read dekker allerede OKFs list/search/read).
  • Second brain: NEI — bor i dag i ad-hoc org/*.md uten retrieval-mekanisme under chat. OKF fyller et reelt tomrom: struktur + retrieval + vedlikeholds-tooling, vendor-nøytralt, portabelt, bruker-eid.

Lastemodell-skifte (operatør-presisering 2026-06-26 — reverserer tidligere antakelse)

  • Før (antatt): all kontekst injiseres når hver /architect:*-kommando kjøres.
  • Nå (mål): kontekst hentes smart/selektivt per kommando og per interaksjon — fordi de fleste ganger chatter brukeren med pluginen lastet, uten å kjøre kommandoer. Konteksten må være tilgjengelig i fri chat, hentet on-demand, ikke forhåndsinjisert.
  • Implikasjon: «second brain» trenger en retrieval-skill (list → search → read) som er aktiv uavhengig av kommandoer, + en vedlikeholds-mekanisme som holder wikien oppdatert etter hvert som brukeren tilfører kontekst OG etter hvert som OKF-standarden utvikler seg.

OKF v0.1 — kjernekontrakt (verifisert mot spec)

  • Bundle = katalogtre av markdown-filer, ett konsept per fil. Påkrevd frontmatter-felt: type. Anbefalt: title, description, resource (kilde-URI), tags, timestamp. Konsumenter MÅ bevare ukjente felt.
  • Reserverte filnavn: index.md (katalog-enumerasjon, ingen frontmatter, progressiv disclosure), log.md (endringslogg).
  • Kryss-lenking: bundle-relativ (/...) eller relativ markdown; relasjonstype utledes av prosa. Konsumenter må tolerere brutte lenker.
  • v0.1 (12. juni 2026), «starting point, not finished standard» → hold OKF-adopsjonen oppdatert ettersom standarden bumpes (okf_version i rot-index.md).
  • Kilde: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md

Økosystem-digest (les disse FØRST ved implementasjon)

Repo: GoogleCloudPlatform/knowledge-catalog. Mye er GCP/Dataplex/Gemini-bundet (ikke direkte gjenbrukbart); de rene mønstrene vi adopterer er markert.

Konsum / smart retrieval (kjernen — ADOPTER MØNSTERET):

  • samples/enrichment/sample/config/skills/kb-search/SKILL.md — kanonisk skill-basert henteguide. Eksponerer trioen list_contents / read_file / search_content (= progressiv disclosure: finn → åpne kun relevant). Mest verdifulle fil å lese først.
  • samples/enrichment/sample/config/mcp.json + samples/enrichment/src/tools/fileskb/{README.md,main.py} — minimal stdio-MCP-server som eksponerer list/search/read over en markdown-katalog. NB: i Claude Code dekker Grep/Glob/Read dette allerede — egen MCP-server er trolig unødvendig; SKILL-instruksen («søk wikien først, åpne kun relevant») er det bærende.
  • samples/discovery/* — Dataplex-bundet søke-agent (Google ADK + CatalogServiceClient). IKKE gjenbrukbart; kun mønster-referanse.

Struktur / frontmatter-eksempler:

  • okf/bundles/ga4/index.md + okf/bundles/ga4/references/metrics/avg_pageviews.md — ekte index.md-hierarki + leaf-konsept med frontmatter (type/resource/title/description/tags/timestamp) + # Citations-seksjon. Kopier som mal.

Produksjon / vedlikehold (ADOPTER MØNSTERET, ikke koden):

  • okf/src/reference_agent/prompts/web_ingestion_instruction.md — kilde-drevet oppdatering: list_concepts → fetch → enrich/mint/skip med strenge frontmatter-/heading-bevaringsregler. Moden mal for «hold wikien oppdatert fra kilder».
  • okf/src/reference_agent/prompts/reference_instruction.md — deterministisk konsept-syntese (frontmatter + fast body-rekkefølge).
  • okf/src/reference_agent/cli.py — enrich / visualize-kommandoer (Gemini/BQ-bundet impl).
  • toolbox/mdcode/{README.md,docs/concept.md,src/tool/mcp.ts} — «metadata as code» bidireksjonell sync mot Dataplex. Sync-enden er GCP-spesifikk; kun konseptet (lokal markdown = source of truth) er relevant.

Hva som må bygges (fremtidige faser — ikke nå)

  1. Frontmatter-/struktur-konvensjon for second brain: minimal OKF-konform (type påkrevd + source/timestamp), index.md per nivå. Migrer dagens org/*.md (de mangler bare type: — nær OKF allerede).
  2. Retrieval-skill («second-brain-search» e.l.): list → search → read over ~/.claude/ms-ai-architect/org/, aktiv i fri chat (ikke bare kommandoer). Avgjør: ren SKILL+Grep/Glob/Read vs. dedikert MCP-server (build-both-and-measure-kandidat — se under).
  3. Vedlikeholds-mekanisme: hvordan wikien oppdateres når brukeren tilfører kontekst (onboarding-agent skriver OKF-konform), + en oppdaterings-rutine når OKF-standarden bumpes.

Åpne valg (operatør / måling)

  • Retrieval-mekanisme: SKILL + native Grep/Glob/Read vs. dedikert fileskb-MCP-server. Ekte tvil → kandidat for «implementer begge, mål hvilken gir best kontekst-treff for brukeren» (operatørs faktabasert-prinsipp).
  • Hvor mye av OKF formaliseres: full v0.1-konformitet vs. «OKF-kompatibel form» (frontmatter + index.md uten resten). Lén mot det letteste som gir smart retrieval.
  • Oppdaterings-kadens mot standarden: hvordan fange OKF-versjonsbump (v0.1 → …) uten manuell polling.

Suksesskriterium (per operatør 2026-06-26)

Det viktigste er ikke teknologien, men at second brain blir så bra som mulig for brukeren og at oppdateringsmekanismene fungerer veldig bra. Mål mot brukerverdi (henter pluginen riktig personlig/org-kontekst i chat?) + vedlikeholds-pålitelighet — ikke mot formell OKF-konformitet i seg selv.

Referanser