voyage/docs/deep-research-engine-brief.md

type	brief_version	task	slug	framing	status	brief_quality	research_topics	research_status	phase_signals_partial
trekbrief	2.2	Opt-in /deep-research-motor for /trekresearch ekstern-fase	deep-research-engine	refine	ready	complete	3	complete	true

Brief — Opt-in /deep-research-motor for /trekresearch

TL;DR

• --engine {swarm|deep-research} på /trekresearch ekstern-fase; swarm default (uendret oppførsel).
• deep-research delegerer ekstern research til Claude Codes innebygde workflow og adapterer inn i research-brief-skjemaet.
• Lokal analyse, triangulering og H2-output (research/NN-*.md) er motor-uavhengig.
• Feature-detekteres med auto-fallback til swarm — aldri hard feil.
• Surface-only: commands/ + agents/, ingen nye lib/-avhengigheter.

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 "<q>" gir identisk oppførsel som før (regresjon grønn).
2. /trekresearch --external --engine deep-research "<q>" 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 <dir> --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.

Research-status (2026-06-30, operatør-beslutning «option A»): Topic 1 (eneste ekte eksterne ukjente) er undersøkt → docs/deep-research-engine-research.md (validator-grønn). Funn: /deep-research er en innebygd dynamic workflow (ikke skill) → trigging KUN via prosa-instruksjon, output inline i kontekst (ingen on-disk-artefakt) → motoren må være instruksjons-basert + in-context transform. SC3 er korrekt som skrevet (/deep-research ER en dynamic workflow). Topic 2 (validator-skjema: type/created/question + ## Executive Summary/## Dimensions, dimensions ≥ 1) og topic 3 (fallback-plassering) er lokale kode-spørsmål reklassifisert til /trekplan-utforskning. research_status: complete reflekterer denne beslutningen.

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.