93 lines
6.7 KiB
Markdown
93 lines
6.7 KiB
Markdown
# Deep-Research Dispatch Template — `create-plan` Phase 1
|
||
|
||
> **This is the exact prompt template the curator uses in Phase 1 to convert the frozen brief into a focused `deep-research` dispatch.** The curator fills in `<FOCUSED_QUESTION>` from the brief (rules below), runs the pre-dispatch check, and dispatches. Output is captured into `<topic>_research.md`.
|
||
|
||
---
|
||
|
||
## 1. Pre-Dispatch Reasoning Check (MANDATORY)
|
||
|
||
Run these commands before dispatching. Hard gate — do not dispatch without it.
|
||
|
||
```bash
|
||
# 1. Read research profile's current model + reasoning_effort
|
||
grep -E "default:|reasoning_effort:" ~/.hermes/profiles/research/config.yaml | head -5
|
||
|
||
# 2. If reasoning_effort is NOT at max:
|
||
hermes -p research config set agent.reasoning_effort max
|
||
# (Use 'xhigh' for models that support it; 'max' is the safe universal default.)
|
||
```
|
||
|
||
`max` is the highest effort setting universally supported by all models. The research profile's reasoning effort is the one that matters — your own (general/curator) profile is already configured. Do not modify your own profile.
|
||
|
||
---
|
||
|
||
## 2. The Dispatch Command (parameterized)
|
||
|
||
```bash
|
||
hermes -p research -s deep-web-research chat -q "<FOCUSED_QUESTION>" -Q --max-turns 600 --yolo
|
||
```
|
||
|
||
Flag rationale (matches `deep-research` v2.1.0; `-s deep-web-research` loads the deep-web-research sub-skill of the deep-research dispatcher):
|
||
- `-p research` — required profile flag (sticky default may be general)
|
||
- `-s deep-web-research` — required skill flag; loads the six-move research methodology
|
||
- `-Q` — one-shot mode, no REPL
|
||
- `--max-turns 600` — ceiling, not budget; matches operator's "no turn restriction, correctness over speed" rule
|
||
- `--yolo` — required for headless execution; approval prompts fail closed without it
|
||
- **NO `--model` override** — the research profile's default model is the source of truth
|
||
|
||
**Output capture:**
|
||
- Output line 1: `session_id: <id>` — capture this
|
||
- Output line 2+: the research agent's condensed answer (relay verbatim — do not re-condense)
|
||
- The research agent also writes its full findings to `/tmp/research-<sid>.md` (external ledger) — read both
|
||
|
||
---
|
||
|
||
## 3. Focused-Question Derivation (the value-add)
|
||
|
||
**Precedence (read first):** Q1 sets the topic, Q2 sets the hard limits, Q3 sets the definition of done, Q4 becomes `CRITICAL:` sub-directions. Q5–Q10 contribute dimensions if relevant.
|
||
|
||
The focused question is what makes Phase 1 produce evidence the plan can cite verbatim. Derivation rules:
|
||
|
||
1. **Anchor on Q1 (Scope)** from the frozen brief. The scope answer is the topic.
|
||
2. **Add Q2 (Constraints)** as hard limits — must-use / must-avoid / target environment narrow the search space.
|
||
3. **Add Q3 (Success criteria)** as the definition of "done" for the research — what would the research need to find for the plan to be buildable?
|
||
4. **The question must drive 3+ search angles** — multiple source types (official docs, GitHub, PyPI, release notes, tutorials, known-issue trackers).
|
||
5. **The question must justify 600 turns of investigation** — vague questions get shallow landscape passes and burn turns without producing load-bearing evidence.
|
||
6. **Do NOT include the curator's own assumptions** — only constraints derived from the operator's brief answers.
|
||
7. **Q4 (Known unknowns) is always processed.** Concerns the operator named become `CRITICAL:` sub-directions. If Q4 was skipped or answered "none", the question still includes a "common unknowns to disconfirm" clause to ensure disconfirmation discipline (e.g., "CRITICAL: verify no recent CVEs, no deprecation notices, no license changes in the last 12 months").
|
||
|
||
**Format (use this skeleton, fill in from the brief):**
|
||
|
||
```
|
||
Exhaustive deep research: [topic from Q1]. [1-2 sentence scope framing from Q1]. Cover: [list of dimensions derived from brief Q2-Q10 if relevant — e.g., scheduling tool, deduplication, retention, encryption, restore verification, alerting]. For each dimension: [what to find — name, current version, official setup steps, hardware/dependency requirements, license, key commands]. CRITICAL: [any specific concerns the operator raised in Q4 — e.g., "must work on NixOS", "avoid Docker", "license must be MIT", "compatibility with Python 3.13"]. Format as comprehensive markdown with full details, options, trade-offs, and source URLs.
|
||
```
|
||
|
||
**Worked example** (Q1 = "cron job that backs up workspace daily"):
|
||
|
||
```
|
||
Exhaustive deep research: daily workspace backup cron job in 2026. A reliable, low-maintenance scheduled backup of a Linux user workspace, run unattended, with restore verification. Cover: scheduling tool (cron vs systemd-timer), backup engine (rsync vs restic vs borg vs btrfs-snap), deduplication strategy, retention policy, encryption at rest, restore verification, alerting on failure, integration with existing cron/systemd on a standard Proxmox host. For each option: current stable version, official setup steps, hardware/disk requirements, license, key commands for backup and restore. CRITICAL: must work on a single-user homelab with no managed monitoring stack; operator wants minimal ongoing maintenance; restore must be testable without overwriting live data. Format as comprehensive markdown with full details, options, trade-offs, and source URLs.
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Output Handling (read both channels)
|
||
|
||
- **Stdout (condensed):** the research agent's terminal output. Synthesis — the answer the research agent already condensed. Relay verbatim, do not re-condense.
|
||
- **External ledger (full):** `/tmp/research-<sid>.md` — every finding, every source URL, every credibility tier. The evidence.
|
||
|
||
**Spot-check rule:** the research agent's self-reports are not verified fact. If it claims a specific finding, spot-check the source URL. If it claims a file write, `read_file` the path to confirm.
|
||
|
||
The curator captures both and writes `<topic>_research.md` to the target save dir (`~/workspace/plans/`). The structure of `<topic>_research.md` is defined in `curator-framing-prompt.md` Step 1.4 — this template is only the dispatch step.
|
||
|
||
---
|
||
|
||
## 5. Failure Handling
|
||
|
||
If deep-research errors out, retry ONCE with the same prompt. If still failing, finalize the plan with header note `"Research phase failed. Plan based on operator-provided brief only. Currency cannot be guaranteed."` Continue to Phase 2 with whatever evidence you have (or skip research-derived steps in the plan).
|
||
|
||
**Do not retry more than once.** Two failed dispatches means the research profile itself is broken — escalate to operator, do not loop.
|
||
|
||
---
|
||
|
||
**Pipeline position:** Phase 0 (dispatcher, brief) → **Phase 1 (this template, deep-research)** → Phase 2 (curator, assemble) → Phase 3 (curator, self-review) → Phase 4 (curator → ask-claude, evidence-diff) → Phase 5 (curator, URL re-verify) → Phase 6 (curator, reconcile).
|