102 lines
4.9 KiB
Markdown
102 lines
4.9 KiB
Markdown
---
|
|
name: research-driven-debugging
|
|
description: When a build or config fails, dispatch research (better-search/deep-research) to resolve issues rather than guessing at fixes. Triggered by build failures with complex configs, unknown tool behavior, or fast-moving APIs.
|
|
version: 1.0.0
|
|
author: Hermes Agent
|
|
metadata:
|
|
hermes:
|
|
tags: [debugging, research, build, config, validation]
|
|
related_skills: [systematic-debugging, better-search, deep-research]
|
|
---
|
|
|
|
# Research-Driven Debugging
|
|
|
|
## Overview
|
|
|
|
When a build task fails due to configuration errors (wrong field names, step values, scheduler choices, model paths), do NOT guess at fixes. Dispatch research to the research profile to validate the config against current community knowledge, then apply the findings.
|
|
|
|
This pattern extends `systematic-debugging` Phase 1 (Root Cause Investigation) with a specific tool: research dispatch. It sits between "I don't know what's wrong" and "I'll try random fixes."
|
|
|
|
## Trigger
|
|
|
|
Any of:
|
|
- Build task fails with a config/API error from a fast-moving tool (ComfyUI nodes, GGUF loaders, model configs)
|
|
- Peer agent reports validation errors in a JSON payload you wrote
|
|
- You're about to guess at a fix for a tool you haven't researched
|
|
- User says "do deep search to resolve issues" or "research this first"
|
|
|
|
## Pattern: Build-Fail-Research-Fix-Rebuild
|
|
|
|
### Step 1: Build
|
|
Write the build task file with the best available knowledge.
|
|
|
|
### Step 2: Fail
|
|
The build fails or the peer reports config errors. STOP. Do NOT guess.
|
|
|
|
### Step 3: Research
|
|
Dispatch `better-search` or `deep-research` to validate the config:
|
|
|
|
```bash
|
|
# Medium-depth (config validation, known tool, 2-3 targeted searches)
|
|
research -s better-search-research chat -q "<specific config question>" -Q --max-turns 50 --yolo
|
|
|
|
# Deep (new tool, unknown compatibility, exhaustive coverage)
|
|
hermes -p research -s deep-web-research chat -q "<broad research question>" -Q --max-turns 600 --yolo
|
|
```
|
|
|
|
Search targets: GitHub issues, HuggingFace discussions, Reddit, official docs, CivitAI workflows.
|
|
|
|
### Step 4: Fix
|
|
Apply the research findings to the build task file. Use `patch` for targeted edits.
|
|
|
|
### Step 5: Rebuild
|
|
Re-dispatch the peer with the corrected build task.
|
|
|
|
## When to Use Which Research Tier
|
|
|
|
| Situation | Tool | Turns | Time |
|
|
|-----------|------|-------|------|
|
|
| Config validation, known tool, specific version | `better-search` | 3-loop cap | ~2-5 min |
|
|
| New tool, unknown compatibility, landscape mapping | `deep-research` | 200+ | ~10-30 min |
|
|
|
|
## Anti-Patterns
|
|
|
|
- **Guessing at fixes.** Running 2-3 `mcp_searxng_searxng_web_search` calls and guessing. That's a casual lookup, not research. Dispatch.
|
|
- **Skipping research because "it's probably X."** If you're wrong, you waste the peer's turns discovering the real bug. Research first.
|
|
- **Using deep-research for simple config validation.** A single field name fix doesn't need 200 turns. Use `better-search`.
|
|
|
|
## Pitfall: better-search Result Not Saved to Disk
|
|
|
|
The better-search dispatcher writes results to `~/workspace/research/results/<date>-<slug>.md`. Sometimes the file isn't created (the research agent may output to stdout only). When this happens, do NOT re-dispatch — read the source code directly instead.
|
|
|
|
**Real example (2026-07-21):** better-search for LTX Director timeline format returned results to stdout but didn't write a result file. The answer was found by reading `ltx_director.py` source code on the target machine — the `_load_image_tensor()` function revealed the correct field names (`imageFile`, not `image`).
|
|
|
|
**Pattern:** `grep` the source code for the relevant function, read the validation logic, and extract the exact field names/format. This is faster than re-dispatching research and more reliable than guessing.
|
|
|
|
## References
|
|
|
|
- `references/ltx-director-timeline-format.md` — Exact JSON format for LTX Director timeline_data
|
|
- `references/comfyui-workflow-api-conversion.md` — ComfyUI save format → API format conversion
|
|
- `references/wan22-lightning-lora-gguf-findings.md` — Wan 2.2 Lightning LoRA config findings
|
|
|
|
## Real Example
|
|
|
|
**Context:** Wan 2.2 I2V-A14B GGUF + Lightning LoRA speed test. Build task JSON had three bugs.
|
|
|
|
**Research dispatched:** `better-search` to research profile. 8 searches, 12 sources, 5 areas investigated.
|
|
|
|
**Bugs found:**
|
|
- `start_step`/`end_step`: `0→1, 2→3` → `0→2, 2→4` (end_step is exclusive)
|
|
- Scheduler: `dpm++_sde` → `euler` (dpm++_sde fails with Lightning LoRA)
|
|
- LoRA input field: `lora_name` → `lora` with correct path prefix
|
|
|
|
**Sources:** GitHub issues (kijai/ComfyUI-WanVideoWrapper #976, #998), HuggingFace (bullerwins, Kijai), CivitAI, Reddit.
|
|
|
|
**Result:** All three fixes applied, rebuild succeeded on first attempt.
|
|
|
|
## See Also
|
|
|
|
- `systematic-debugging` — 4-phase root cause debugging. This skill extends Phase 1 with research dispatch.
|
|
- `better-search` — Medium-depth research dispatcher. Use for config validation.
|
|
- `deep-research` — Exhaustive research dispatcher. Use for new/unknown tools.
|