comprehensive-research-agent

Comprehensive Research Agent Best Practices

This skill addresses common failures in multi-step research tasks: unhandled tool errors, missing validation, opaque reasoning, and premature conclusions. It provides structured protocols for source validation, error recovery, and thinking transparency that significantly improves research quality and reliability.

When to Activate

• Task involves web research with search, read_url, or fetch operations
• Task requires gathering information from multiple sources
• Task has explicit requirements for completeness or verification
• Task includes file operations that need validation (save, write, read)
• Any research or information-gathering workflow with 3+ tool interactions

Core Concepts

• Validation Checkpoints: Explicit verification steps at phase transitions to confirm tool outputs, source relevance, and information completeness before proceeding
• Error Recovery Protocols: Mandatory acknowledgment and handling of tool failures with fallback strategies rather than silent continuation
• Source Traceability: Maintaining clear tracking of which sources were actually retrieved vs. referenced from prior knowledge to prevent hallucination
• Substantive Thinking Blocks: Detailed reasoning traces that document insights, connections, gaps, and decision rationale at each step
• Cross-Source Validation: Verifying key claims against multiple sources and explicitly noting consensus, contradictions, and information gaps

Patterns to Avoid

• Silent Tool Failure*: A tool call returns an error (404, timeout, invalid URL) but the agent proceeds without acknowledging it, potentially missing critical information. Always log failures and attempt recovery or document the gap.
• Vague Completion Claims*: Agent declares 'I have enough information' or 'research is comprehensive' without specifying what was learned, what sources support claims, or what gaps remain. Replace with specific summaries of coverage.
• Unvalidated Source Selection*: Agent reads URLs from search results without evaluating relevance, credibility, or recency first. This wastes tool calls on low-quality sources. Always rank and prioritize sources before deep reading.
• Generic Thinking Blocks*: Thinking contains only next-action descriptions ('Now I will search for X') without analysis of what was learned, how it connects to the goal, or what questions remain. Thinking should be substantive and reflective.
• Verification Method Error*: Using list_directory to verify file creation can produce false negatives due to caching. Always use read_file for actual content verification.
• Citation Without Retrieval*: Citing sources (URLs, paper titles) in the final report that were never successfully fetched or read. Track sources explicitly and prohibit citing unretrieved content.
• Redundant Tool Calls*: Making overlapping searches or reading sources without tracking what has already been obtained. Maintain a 'found resources' tracker to avoid duplication.