Kjell Tore Guttormsen
d98cce371a
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).
61 lines
7.5 KiB
Markdown
61 lines
7.5 KiB
Markdown
# 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
|
|
- Spec: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
|
|
- Samples: https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/samples
|
|
- Toolbox: https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/toolbox
|
|
- Relatert (skill-ref-sporet, separat): `docs/ref-kb-direction-note-2026-06.md`, `docs/ref-kb-audit-2026-06.md`
|