diff --git a/docs/deep-research-engine-brief.md b/docs/deep-research-engine-brief.md new file mode 100644 index 0000000..b7d1c78 --- /dev/null +++ b/docs/deep-research-engine-brief.md @@ -0,0 +1,48 @@ +--- +# Avstem frontmatter mot lib/validators/brief-validator.mjs før /trekplan +brief_version: "2.2" +status: draft +brief_quality: complete +research_topics: 3 +--- + +# Brief — Opt-in `/deep-research`-motor for `/trekresearch` + +## Intent +`/trekresearch` eier i dag hele den eksterne research-fasen selv (Tavily / MS-Learn / Gemini-sverm). Det er portabelt, men du vedlikeholder fan-out, kryssjekk og syntese selv. Anthropic sin innebygde `/deep-research` vedlikeholder fan-out, adversariell påstandsverifisering, sitatfiltrering og websøk for deg. Lar vi operatøren *velge* `/deep-research` for den eksterne fasen, får brukeren en vedlikeholdsfri "turbo" når den er tilgjengelig — uten at Voyage mister sin egen lokal-analyse, triangulering eller H2-kontrakt. + +## Goal +`/trekresearch` får et `--engine {swarm|deep-research}`-valg på den eksterne fasen. `swarm` er default (dagens oppførsel). `deep-research` delegerer den eksterne fasen til den innebygde workflowen og adapterer resultatet inn i research-brief-skjemaet. Lokal analyse, triangulering og H2-output (`research/NN-*.md`) er uendret uansett motor. + +## Non-Goals +- Bygge om `/trekresearch` på et eget dynamic-workflow-substrat (vurdert og forkastet, Δ≈0). +- Multi-provider (Perplexity / Google) — hører til en senere egen `workflow`-motor, ikke denne. +- Endre den lokale svermen, handover-kontraktene eller validator-skjemaene. +- Gjøre `/deep-research` til default. + +## Constraints / NFR +- `/deep-research` krever Claude Code v2.1.154+ og må være på (Pro: via `/config`). Må feature-detekteres med auto-fallback til `swarm` — aldri hard feil. +- Output må passere `research-validator.mjs` (confidence ∈ [0,1], dimensions ≥ 1, påkrevde body-seksjoner). +- Ingen nye `lib/`-avhengigheter; overflate-endring i `commands/` + `agents/`. +- Doc-consistency: oppdater command-tabellen i `CLAUDE.md` + `README.md`, kjør `npm test`. + +## Success Criteria +1. `/trekresearch --external --engine swarm ""` gir identisk oppførsel som før (regresjon grønn). +2. `/trekresearch --external --engine deep-research ""` produserer en `research/NN-*.md` der `research-validator.mjs --json` rapporterer `valid: true`. +3. Med dynamic workflows avskrudd faller `--engine deep-research` automatisk tilbake til `swarm` og logger valget — ingen exception. +4. `npm test` (inkl. doc-consistency) er grønn. + +## Research Plan +1. **Programmatisk trigging av `/deep-research`** — Kan en plugin-kommando starte den innebygde workflowen og fange artefakten, eller må `commands/trekresearch.md` instruere Claude til å kjøre den? Scope: external · Konfidens: høy · Kost: lav. + `/trekresearch --external "Kan en Claude Code plugin-kommando programmatisk starte /deep-research og hente rapporten?"` +2. **Output-adapter** — Hvordan mappe `/deep-research` sin siterte rapport til research-brief-skjemaet (dimensjoner, confidence, sitater)? Scope: both · Konfidens: høy · Kost: lav. + `/trekresearch --project --local "Hva krever research-validator.mjs av research/NN-*.md?"` +3. **Feature-deteksjon + fallback** — Hvordan oppdage om workflows er på, og hvor i fasen fallback-grenen bør sitte? Scope: local · Konfidens: middels · Kost: lav. + +## Open Questions / Assumptions +- Antar at `/deep-research`-rapporten kan reduseres til ≥ 1 dimensjon med per-påstand-sitater uten å bryte trianguleringen. Verifiseres i topic 2. +- Uavklart om delegering skjer via instruksjon (trygt) eller programmatisk API (raskere) — topic 1 avgjør. + +## Prior Attempts +- Dvalende synthesis-agent bygget, målt (Δ≈0) og forkastet → samme lærdom gjelder substrat-bytte: mål før du adopterer. +- Workflow-substratet er allerede dokumentert som vurdert-og-valgt-bort i `docs/architecture.md` §Primitives per step.