hermes-skills/research-driven-debugging/SKILL.md

name, description, version, author, metadata

name	description	version	author	metadata
research-driven-debugging	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.	1.0.0	Hermes Agent	hermes tags related_skills debugging research build config validation 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:

# 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.