diff --git a/docs/deep-research-engine-brief.md b/docs/deep-research-engine-brief.md index ac22280..bd779eb 100644 --- a/docs/deep-research-engine-brief.md +++ b/docs/deep-research-engine-brief.md @@ -4,10 +4,10 @@ brief_version: "2.2" task: "Opt-in /deep-research-motor for /trekresearch ekstern-fase" slug: deep-research-engine framing: refine -status: draft +status: ready brief_quality: complete research_topics: 3 -research_status: pending +research_status: complete phase_signals_partial: true --- @@ -51,6 +51,8 @@ phase_signals_partial: true `/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. +> **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. diff --git a/docs/deep-research-engine-research.md b/docs/deep-research-engine-research.md new file mode 100644 index 0000000..d65a13a --- /dev/null +++ b/docs/deep-research-engine-research.md @@ -0,0 +1,210 @@ +--- +type: trekresearch-brief +created: 2026-06-30 +question: "Can a Claude Code plugin command programmatically trigger the built-in /deep-research workflow and capture its report, or must it instruct Claude to run it?" +confidence: 0.85 +dimensions: 4 +mcp_servers_used: [] +local_agents_used: [claude-code-guide] +external_agents_used: [] +slug: deep-research-engine +feeds_brief: docs/deep-research-engine-brief.md +research_topic: 1 +--- + +# Research — Programmatic trigging of `/deep-research` from a plugin command + +> Targeted single-topic research for the `deep-research-engine` brief (Topic 1 of +> the brief's Research Plan). Topics 2 & 3 are local Voyage-code questions folded +> into `/trekplan` exploration; only Topic 1 was a genuine external unknown. +> Method: `claude-code-guide` agent (Anthropic docs + CHANGELOG, cited) + +> direct inspection of this machine (CC 2.1.196 binary, a real local `/deep-research` +> run). Not run through the `/trekresearch` swarm — see brief reconcile note. + +## Research Question + +Can a Claude Code **plugin slash-command** (markdown under `commands/`) +**programmatically** start the built-in `/deep-research` workflow and **capture its +report artifact** for adaptation into the research-brief schema — or must the command +instead **instruct** Claude (in prose) to run `/deep-research` and then transform the +in-context result? + +## Executive Summary + +Programmatic trigger + file-based capture is **not feasible**: `/deep-research` is a +built-in **dynamic workflow** (not a skill), deliberately outside the Skill-tool +allowlist, and it returns its report **inline into conversation context with no +documented on-disk report artifact**. The **only reliable path is instruction-based +delegation** — the command's prose tells Claude to run `/deep-research `, then +transforms the in-context report in the same turn. Confidence **high** (Anthropic docs + +CHANGELOG + local run), with one residual gap: there is no positive "is it enabled?" +probe, so feature-detection must lean on the documented *disable* switches + version +floor + a `swarm` default. + +## Dimensions + +### 1. Origin + gating -- Confidence: high + +**External findings:** +- `/deep-research` is a **built-in dynamic workflow**, not a command and not a bundled + skill. `commands.md` marks the `/deep-research ` row as **[Workflow]**; + `workflows.md`: "Claude Code includes `/deep-research` as a built-in workflow." + [VERIFIED — code.claude.com/docs/en/commands.md, code.claude.com/docs/en/workflows.md] +- Gating: available on **all paid plans** (pro/max/team/enterprise) + API/Bedrock/Vertex/ + Foundry. **On Pro it must be turned on** in the *Dynamic workflows* row of `/config`. + Also requires the **WebSearch tool** to be available. + [VERIFIED — workflows.md, commands.md bundled-workflows row] +- Version floor: dynamic workflows were **introduced in CC 2.1.154**; "Dynamic workflows + require Claude Code v2.1.154 or later." The brief's `v2.1.154+` + `(Pro: via /config)` + constraints are **both correct**. The exact version that first shipped the *named* + `/deep-research` workflow is **[NOT DOCUMENTED]** (only a 2.1.196 bugfix mentions it by + name) — treat 2.1.154 as the substrate floor, not a proven introduction point. + [VERIFIED — workflows.md + CHANGELOG 2.1.154] + +**Local findings:** +- This machine runs **CC 2.1.196** (`claude --version`) — substrate floor satisfied. +- The exact skill-description string lives **compiled into the binary** + (`/Users/ktg/.local/share/claude/versions/2.1.196`, Mach-O 235 MB); there is **no + `SKILL.md`** for it anywhere under `~/.claude` (system-wide `find`/`grep` — only hits + are this brief + unrelated harness notes). Confirms "Anthropic-bundled, not user skill." + +### 2. Invocation mechanism (programmatic vs instruction) -- Confidence: high + +**External findings:** +- **Not** via the `Skill` tool. The Skill-tool built-in allowlist is closed: only + `/init`, `/review`, `/security-review` are reachable; "Other built-in commands such as + `/compact` are not." `/deep-research` is a Workflow and is not on that list. + [VERIFIED — code.claude.com/docs/en/skills.md] +- **Instruction-based delegation is the documented mechanism.** Workflows launch when the + user types the command, or **when Claude is asked in natural language** ("use a + workflow" / "run a workflow") or via the `ultracode` keyword. A plugin command whose + markdown instructs Claude to run `/deep-research ` is therefore the supported path. + [VERIFIED — workflows.md "Have Claude write a workflow"] +- **Approval gate caveat:** launching a workflow triggers a per-run approval prompt — + *every run* in default/acceptEdits; *first launch only* in auto; **never in `claude -p` + / Agent SDK / bypass-permissions** ("the run starts immediately"). Voyage's headless + surface (`claude -p`) thus delegates without an interactive gate; interactive sessions + hit a prompt. [VERIFIED — workflows.md "Behavior and limits"] +- No documented blanket "commands/skills cannot nest" prohibition beyond the Skill-tool + allowlist + workflow runtime limits (no mid-run user input; 16 concurrent agents; + 1000 agents/run). [VERIFIED — workflows.md; NOT DOCUMENTED for a general nesting ban] + +### 3. Output capture -- Confidence: high + +**External findings:** +- "When the run finishes, **the report lands in your session**"; "Claude's context holds + only the final answer." The report is **in-context**, not a file. + [VERIFIED — workflows.md] +- What *is* written to disk is the orchestration **script**, not the report: "Every run + writes its script to a file under your session's directory in `~/.claude/projects/`." + [VERIFIED — workflows.md "How a workflow runs"] + +**Local findings:** +- A real `/deep-research` run on this machine left exactly one file — + `~/.claude/projects//workflows/scripts/deep-research-wf_.js` — and **no + `.md` report** beside it. [VERIFIED — local filesystem inspection by claude-code-guide] +- **Consequence:** a calling command cannot `grep` a results file off disk (none is + documented to exist). It can only consume the report **as it sits in conversation + context in the same turn** — Claude reads its own prior output and transforms it into + research-brief schema. [INFERENCE — file-based capture not feasible; in-context + transform is the only avenue] + +### 4. Feature detection + fallback -- Confidence: medium + +**External findings:** +- **No positive enumeration / "is-enabled" API or flag is documented.** `claude --help` + exposes `--disable-slash-commands` but no "list skills/workflows" or "is-feature-on" + flag. [VERIFIED — local `claude --help`; NOT DOCUMENTED for any positive probe] +- The documented signals are the **off-switches**, read defensively: `/config` Dynamic- + workflows off; `disableWorkflows: true` / `disableBundledSkills: true` in settings.json; + `CLAUDE_CODE_DISABLE_WORKFLOWS=1` / `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1`. + [VERIFIED — workflows.md "Turn workflows off"; CHANGELOG 2.1.x] +- **The gap:** the Pro `/config` *on*-state is the very thing you most need to detect, and + only the *disable* keys are documented; the persisted key/value for the Pro enable-state + is **[NOT DOCUMENTED]**, so it cannot be reliably grepped. A failed/disabled + `/deep-research` is also **not documented** to raise a signal a sibling command can + catch. [VERIFIED gap] + +**Local findings:** +- On this machine both disable keys are unset/absent — workflows are not disabled. + +## External Knowledge + +### Best Practice +The "Have Claude write a workflow" + "Behavior and limits" sections of `workflows.md` +establish that workflows are operator/Claude-launched, run isolated, and return one +in-context report. The Skill-tool allowlist (`skills.md`) is the authoritative statement +that only three built-ins are tool-invocable. + +### Known Issues +Per-run approval prompts outside `-p`/SDK/bypass mean an interactive `/trekresearch +--engine deep-research` will pause for operator approval on each launch — acceptable, but +worth documenting in the command UX. The absence of a positive availability probe is the +single biggest design constraint (see Dimension 4). + +## Synthesis + +Three cross-cutting insights that only emerge from combining the docs with Voyage's brief: + +1. **The brief's SC3 is correct as written — an earlier review note was wrong.** Because + `/deep-research` *is itself* a dynamic workflow, "med dynamic workflows avskrudd faller + `--engine deep-research` tilbake til swarm" is the right feature-detection axis. A + prior brief-review remark that SC3 "conflated `/deep-research` (skill) with dynamic + workflows" was based on a wrong premise (that `/deep-research` was a skill) and is + retracted. **No SC3 brief edit is needed.** + +2. **The engine must be instruction-based + in-context, never file-based.** Topic 1's + open question ("instruction (safe) vs. programmatic API (faster) — topic 1 decides") + resolves decisively to **instruction-based**: there is no programmatic API and no + on-disk report. The `deep-research` engine path in `commands/trekresearch.md` must + (a) instruct Claude to run `/deep-research `, then (b) transform the in-context + report into the `research/NN-*.md` schema in the same turn. This is surface-only + (`commands/` prose), matching the brief's "ingen nye `lib/`-avhengigheter." + +3. **SC3's "ingen exception" cannot rest on runtime detection — pin it to a default.** + Since no positive availability probe exists, robust fallback = version-floor check + (≥ 2.1.154) + disable-key heuristic (`disableWorkflows` / env) + **`--engine` default + of `swarm`** (explicit opt-in). The fallback is "graceful degradation by design," + not "catch an exception at runtime." This refines, but does not contradict, SC3. + +## Open Questions + +- **Adapter fidelity (brief Topic 2, partly answered locally):** `research-validator.mjs` + requires `type: trekresearch-brief` + `created` + `question`; validates `confidence ∈ + [0,1]` and `dimensions ≥ 1` if present; body must carry `## Executive Summary` + + `## Dimensions`. So the `/deep-research` report **can** be reduced to ≥ 1 dimension with + per-claim citations and a confidence number — the brief's assumption holds. The + remaining open part (how cleanly the in-context report maps to per-dimension + local/external splits) is a `/trekplan` exploration concern, not an external unknown. +- **Exact intro version of the *named* `/deep-research` workflow** — not documented; the + 2.1.154 dynamic-workflows floor is the safe pin. + +## Recommendation + +Build the `deep-research` engine as **instruction-based delegation with in-context +adaptation**, not a programmatic trigger: +1. `--engine deep-research` makes `commands/trekresearch.md`'s external phase instruct + Claude to run `/deep-research ` and transform the returned in-context report into + `research/NN-*.md` (validator-conformant: `## Executive Summary` + `## Dimensions`, + `confidence`, `dimensions ≥ 1`). +2. Feature-detect by **graceful degradation**: version floor + disable-key heuristic + + `--engine` default `swarm`. Do not depend on a positive availability probe (none + exists). Log the chosen engine. This satisfies SC3 without a runtime exception. +3. Keep `swarm` the default (brief's Non-Goal: "ikke default-bytte"). Document the + per-run approval prompt for interactive (non-`-p`) sessions. + +Confidence in the recommendation: **high** for the mechanism (instruction-based + +in-context), **medium** for the exact fallback-detection ergonomics (the one documented +gap). This is sufficient to green-light `/trekplan` with Topic 1 resolved. + +## Sources + +| # | Source | Type | Quality | Used in | +|---|--------|------|---------|---------| +| 1 | code.claude.com/docs/en/workflows.md | official | high | Dim 1,2,3,4 + Synthesis | +| 2 | code.claude.com/docs/en/commands.md | official | high | Dim 1 (Workflow classification, WebSearch req) | +| 3 | code.claude.com/docs/en/skills.md | official | high | Dim 2 (Skill-tool allowlist) | +| 4 | github.com/anthropics/claude-code CHANGELOG (2.1.154, 2.1.x, 2.1.196) | official | high | Dim 1,4 (version floor, disable keys) | +| 5 | Local: CC 2.1.196 binary inspection (`find`/`grep`, `claude --version`) | codebase | high | Dim 1 (bundled, no SKILL.md) | +| 6 | Local: real `/deep-research` run — only `.js` script written, no `.md` report | codebase | high | Dim 3 (no on-disk artifact) | +| 7 | Local: `lib/validators/research-validator.mjs` schema | codebase | high | Open Questions (adapter feasibility / Topic 2) |