open/voyage
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions
voyage/docs/deep-research-engine-brief.md
Kjell Tore Guttormsen cb5dba9542 docs(brief): add opt-in /deep-research engine brief to backlog 
Records the operator-supplied brief for an --engine {swarm|deep-research}
choice on /trekresearch's external phase (swarm stays default; deep-research
delegates the external phase to the built-in workflow with auto-fallback).
Backlog item only — not implemented. Lives beside the work (docs/), tracked.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BJQYC5vpkJWxndS55vQQZ6
2026-06-30 09:00:40 +02:00

3.7 KiB
Raw Permalink Blame History

brief_version status brief_quality research_topics
2.2 draft complete 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 "<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.

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.