open/voyage
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions
voyage/docs/deep-research-engine-brief.md
Kjell Tore Guttormsen 60e9e7ae5c docs(brief): reconcile deep-research-engine brief to validator-green (2.2) 
Operator-delivered draft (S55) carried only brief_version/status/brief_quality/
research_topics and an explicit "reconcile frontmatter against brief-validator
before /trekplan" note. Add the required fields (type, task, slug,
research_status, phase_signals_partial) plus the brief_version 2.2 gates:
framing: refine (operator-confirmed — additive opt-in engine, swarm stays
default, no contract change) and a 5-line ## TL;DR. brief-validator passes
strict + --min-version 2.2. status stays draft pending operator review before
the /trekplan run.

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

4.3 KiB
Raw Blame History

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 draft complete 3 pending 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.

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.