From 444b9a375a7e2e3304cc6cdba877d6dc8bd98e5a Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Fri, 19 Jun 2026 21:48:03 +0200 Subject: [PATCH] docs(ms-ai-architect): spor onboarding-mekanisme-redesign som kommende fase MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Operatør-flagget kritisk for brukervennlighet (2026-06-19): virksomhetskontekst må være ambient i enhver interaksjon, overleve oppgraderinger/reinstall, og bære fritekst utover de formelle spørsmålene. Dagens mekanisme (org/*.md, gitignored, i plugin-katalog, betinget per-agent-lesing) oppfyller ingen av delene. Brief, ikke godkjent plan — design godkjennes separat. Egen fil i docs/ per ingen-lokale-kontinuitetsmekanismer-regelen. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01REiKFhP4w6xGXXqWKpPCJJ --- docs/onboarding-redesign-brief.md | 46 +++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 docs/onboarding-redesign-brief.md diff --git a/docs/onboarding-redesign-brief.md b/docs/onboarding-redesign-brief.md new file mode 100644 index 0000000..2b31e32 --- /dev/null +++ b/docs/onboarding-redesign-brief.md @@ -0,0 +1,46 @@ +# Brief — Redesign av onboarding-/virksomhetskontekst-mekanismen (ms-ai-architect) + +_Problemstilling + krav, ikke en godkjent plan. Opprettet 2026-06-19 etter operatør-flagg under Sesjon 3 av KB-redesignet. Design godkjennes separat (brief → plan, slik KB-redesignet gikk). **Ikke start implementering uten operatør-go.** Refereres fra `STATE.md`._ + +## Hvorfor dette er kritisk + +Virksomhetskontekst (sektor, lisens, dataklassifisering, budsjett, styringsmodell, regelverk) er det som gjør pluginens output relevant for *denne* brukeren i stedet for generisk. Operatørens vurdering (2026-06-19): hvis denne konteksten ikke er **til stede i enhver interaksjon** og ikke **overlever oppgraderinger**, skaper mekanismen frustrasjon i stedet for verdi — brukeren fyller den ut én gang og opplever at den «forsvinner» eller «ignoreres». + +## Verifisert tilstand i dag (2026-06-19) + +- **Innsamling:** `/architect:onboard` (orkestrator) → `agents/onboarding-agent.md` (5-fase intervju via `AskUserQuestion`, ~13 spørsmål, sektor-forgrening offentlig/privat). +- **Lagring:** `org/*.md` — 5 markdown-filer med YAML-frontmatter (`completed: true`). Plassert **inne i plugin-katalogen**. +- **Konsum:** 11 agenter har en «Virksomhetskontekst (automatisk)»-seksjon som **betinget** leser `org/`-filene («hvis mappen finnes»). +- **Hook:** `hooks/scripts/session-start-context.mjs` viser onboarding-**status** ved sesjonsstart («Ingen virksomhetstilpasning. Kjør /architect:onboard»), men injiserer **ikke** selve innholdet. + +## Gap mot operatør-kravene + +| # | Krav (operatør) | Gap i dag | +|---|---|---| +| 1 | **Ambient i enhver interaksjon** | Org-lesing er opt-in per agent og betinget. Et fritekst-spørsmål eller en kommando uten egen org-seksjon får ikke konteksten. Hooken injiserer status, ikke innhold. | +| 2 | **Overlever oppgraderinger** | `org/` er gitignored (`.gitignore:24`) og bor i plugin-katalogen (`~/.claude/plugins/marketplaces/.../ms-ai-architect/org/`). `git pull` rører den ikke (bra for personvern), men reinstall / re-clone / marketplace-oppdatering til ny katalog **mister den**. Ikke git-backet, ikke backup/restore. | +| 3 | **Fritekst-kontekst utover formelle spørsmål** | Onboarding samler kun strukturerte svar fra faste `AskUserQuestion`-valg. Det finnes ingen «alt annet du vil at pluginen skal vite»-felt (fri prosa) som konteksten kan bære med seg. | + +**Tilstøtende (allerede dokumentert):** `docs/devils-advocate-audit-2026-06-18.md` §167 — onboarding kan ikke representere en privat virksomhet (sektor-valg hardkodet offentlig; reguleringsliste mangler DORA/Finansforetaksloven m.m.). Bør løses i samme redesign siden det treffer samme filer. + +> Merknad: `docs/onboarding-ros-analysis.md` er feildøpt — den er en Windows «clone-to-PR»-guide for ROS-featuren, **ikke** en onboarding-analyse. Vurder å døpe den om i redesignet. + +## Skisserte løsningsretninger (ikke bindende — design godkjennes senere) + +1. **Robust lagringssted.** Flytt org-data ut av plugin-katalogen til en bruker-eid sti som overlever reinstall (f.eks. under `~/.claude/` eller en eksplisitt prosjekt-/bruker-data-mappe), og/eller etabler et eksplisitt eksport/import-mønster. Behold personvern (ikke commit til git). +2. **Ambient injeksjon.** La `session-start-context.mjs` injisere et kompakt org-sammendrag i hver sesjon (slik `STATE.md` injiseres i dag), så konteksten er til stede uavhengig av hvilken agent/kommando som kjøres. Vurder lengde-budsjett. +3. **Fritekst-felt.** Legg til et fritt «ekstra kontekst»-felt i onboarding (én `org/free-context.md` eller seksjon) som bæres med i den ambiente injeksjonen. +4. **Privat-sektor-paritet.** Parametrer sektor-forgreningen så en privat virksomhet ikke er andrerangs (mekanisk endring i `onboarding-agent.md`-spørsmålene + reguleringslister). + +## Verifiserbare akseptansekriterier (for den senere planen) + +- **K1 (ambient):** Start en frisk sesjon med utfylt org-kontekst og still et fritekst-spørsmål uten å invokere en org-bevisst agent → svaret reflekterer minst ett org-faktum. (Bevis: konteksten injiseres, ikke betinget lest.) +- **K2 (overlevelse):** Simuler en oppgradering (flytt/reinstaller plugin-katalogen) → org-konteksten er fortsatt tilgjengelig. (Bevis: lagring utenfor det som blåses bort ved reinstall, eller dokumentert restore-steg.) +- **K3 (fritekst):** Onboarding fanger et fritt prosa-felt, og innholdet er synlig i en etterfølgende interaksjon. +- **K4 (paritet):** En privat virksomhet kan fullføre onboarding uten å velge «Annet» på sektor, med relevant reguleringsliste. + +## Avgrensning + +- **Ikke** en del av KB-mekanisme-redesignet (Sesjon 1–5 + kurs-spor). Eget spor, egen plan. +- Prioriteres etter operatørens vurdering — naturlig kandidat når KB-redesignet (lag 1–3) er på plass, men kan hentes fram tidligere hvis brukervennlighet veier tyngst. +- Følger samme kontinuitetsregler: denne briefen bor i `docs/`, refereres fra `STATE.md`, ingen egen `ROADMAP.md`.