How I built my deep-research skill

In the first part of this deep research post I argued that deep research should focus on what you don’t know. I called it The DIFF: the delta between your existing knowledge and what’s new, changed, or counter-intuitive. That’s the concept. Now let me show you what it looks like when you actually build it.

I’ve been iterating on a deep research skill for Claude Code since late January 2026. Fourteen versions in seven weeks, each one born from a specific failure. Not theoretical improvements. Real misses on real research that mattered to me. The skill today has eight coordinated phases, handles 20-50 sources per run, can decompose a topic across parallel agents, and produces reports that show their work. But it didn’t start there. It started with a prompt and a lot of wrong answers.

This is the practitioner’s walkthrough. The architecture, the failures that shaped it, and the collaboration that sharpened the thinking.

The skill today runs eight phases: PLAN, DIVERGE, CHALLENGE, SEARCH, TRIAGE, READ, REASSESS, SYNTHESIZE. That’s not a simple prompt with a “be thorough” instruction. Each phase has a specific job, specific failure modes it guards against, and specific outputs the next phase consumes.

Let me walk through them using a real example: building a phoneme model for mispronunciation detection in a speech therapy app I’m working on.

PLAN decomposes the query into focused sub-questions and injects personal context. If I ask “research phoneme models,” the plan doesn’t just search for phoneme models. It pulls from my memory files to understand I’m building a speech therapy feature, that I care about real-time performance, that I’m working in Python. Each sub-question targets a specific aspect: what architectures exist, what’s the state of the art, what’s been tried in production.

But here’s the thing. Even a well-decomposed plan carries assumptions from how I framed the question. “Phoneme models” is my vocabulary. It might not be how practitioners in speech pathology or audio ML describe their work.

DIVERGE expands the search space before a single query fires. It generates mechanism-level queries: “speech analysis tools for pronunciation feedback,” “mispronunciation detection systems,” “voice analysis implementations.” These are the terms someone building a solution would use, not the terms someone analysing the space would use. DIVERGE also searches directories and aggregators, and follows entity connections. More on both of those shortly, because they each have a story behind them.

CHALLENGE generates devil’s advocate queries. For each sub-question, it creates contrarian angles: “problems with phoneme-based approaches,” “why phoneme models fail in production,” “alternatives to phoneme analysis for pronunciation.” This is the anti-echo-chamber mechanism. Without it, you search for what you think is right and find confirmation.

SEARCH fires everything in parallel. All the queries from PLAN, DIVERGE, and CHALLENGE go out in a single turn. For a standard research run, that’s 10-20+ parallel web searches. For a thorough run, it can be 30+.

TRIAGE applies diversity and quality filters. Maximum three sources per domain. At least one authoritative source. Perspective diversity is mandatory, not optional. Sources from the CHALLENGE phase get representation even if they’re outnumbered. Each source gets a reputation assessment on a five-tier scale, from authoritative down to unreliable. URLs get deduplicated: not just exact matches, but near-duplicates and syndicated copies of the same article.

READ fetches selected sources in small batches of two to three and extracts relevant content. If link-following is enabled, a second parallel pass grabs sub-pages. The small batch size isn’t arbitrary — it’s a scar from production. WebFetch has no timeout. A single hung URL blocks its entire batch indefinitely. Small batches limit the blast radius. More changes coming to further address this problem that still plagues the current implementation.

REASSESS is the phase I’m most proud of, and it came from the most painful failure. After reading everything, the skill pauses and asks six questions in two categories. Three about framing: did the sources reveal that the original questions were wrong? Did new vocabulary appear that wasn’t in the queries? Is there a gap in coverage that suggests a search strategy failure? And three about claims: which findings are load-bearing? Is anything being conflated? Are any findings suspiciously convenient?

If framing issues surface, it triggers a refinement cycle with new queries. If claims get flagged, it triggers verification with targeted searches. Claims get verdicts: CONFIRMED, CORRECTED, or UNVERIFIABLE. Any correction lowers overall confidence.

SYNTHESIZE produces the final output in two parts: a research file (markdown prose plus a YAML data appendix) and a separate plan file with recommendations. The research file goes to a resources directory. The plan file goes to a plans directory. The separation matters. Research is timestamped facts. Plans are actionable recommendations. When I come back to a topic months later, I want the facts without the stale recommendations attached.

The prose is readable. The appendix is parseable. Follow-up research, fact-checking, or automation can consume the structured data without re-parsing the report. Before synthesis, three mandatory checks fire: contradiction detection across all sources, citation spot-checks against at least three key claims, and confidence tagging, where every claim gets labelled VERIFIED, LIKELY, or UNVERIFIED. That last one was a later addition, born from finding that the REASSESS phase would flag suspicious claims but the final report would present them with equal confidence anyway.

Eight phases feels like a lot. But each one exists because something went wrong without it. Let me tell you about three of those failures.

I was on a call with Akhil Agrawal, the founder of PARA. They’re working on a startup in the deep research space. We were discussing his startup and the deep research market and I offered to run a competitive analysis live while we were talking.

I actually ran my deep research skill twice on the competitive landscape for deep research agent startups. The first pass, during the call, used 25 sources and 24 queries. The second doubled that: 50 sources, 75+ queries. Both passes produced rich, detailed reports. But both passes missed Yutori.

Yutori is a $15M seed startup backed by Fei-Fei Li and Jeff Dean among others, funded by Radical Ventures and Felicis. They’re building autonomous web monitoring agents called “Scouts.” They are squarely in the space I was researching. And neither pass found them.

Akhil told me about them while we were reviewing the report together, otherwise I’d never have known. This is one of the many reminders I constantly get about unknown unknowns… it’s really hard to eval a deep research job for that.

The problem was that the methodology only searched through one channel: Google web search of articles, blogs, and news. Every query followed the same pattern: analyst vocabulary plus category plus year. Yutori was on Product Hunt. It was on Crunchbase. TechCrunch had covered the funding. GlobeNewswire had the press release. But none of the analytical articles about “deep research startups” or “AI knowledge management” mentioned Yutori. It was catalogued, not written about.

Here’s the generalised insight: things that are catalogued but not written about are invisible to keyword-only search. This isn’t just about startups. In academic research, it’s the paper in conference proceedings that never gets cited in survey articles. In job market research, it’s the actual job postings versus the trend pieces about hiring. In company research, it’s what’s on Glassdoor versus what journalists covered. Every research domain has a “written about” channel and a “catalogued” channel. Keyword search only covers the first.

There was a second miss hiding in the same data. Yutori shares investors with Sauna/Wordware, a company the skill did find. Felicis invested in both. But the skill never traversed that connection. It found one node in the graph and stopped.

This drove two new principles in the DIVERGE phase. First, directory and aggregator search: for any research topic, ask “where are the things I’m looking for listed, not just discussed?” Then search those places directly. Second, entity graph traversal: when you find a relevant entity, follow one hop of its relationship graph. Investors, co-founders, shared conference appearances. Not recursive, just one hop, capped at 4-6 queries. Enough to catch the Yutoris.

I updated the skill and ran the research again. The results were much more interesting. And, in a moment of ironic honesty that I still appreciate, the improved methodology still didn’t find Yutori directly. It found new companies, new angles, new connections. But the specific blind spot that started the whole improvement had become a good test of humility.

The second failure was quieter and, in some ways, more dangerous. The skill found information from authoritative sources. Good sources, well-known, high reputation tier. It then inferred something from those sources that was incorrect.

The inference sounded plausible. It appeared in the final report with high confidence. It was the kind of thing you’d read and nod along with. And it was wrong. Four lines of Python could have confirmed or refuted it. But the skill didn’t check. It found, it summarised, it reported. The verification step didn’t exist yet.

This is the failure mode that scares me most about AI research products in general. Not hallucination from nothing, but confident inference from real data that happens to be wrong. The sources were real. The facts were real. The conclusion drawn from combining them was not. And the report gave no indication of uncertainty.

This drove the REASSESS phase. After reading all sources, the skill now explicitly checks for three types of problematic claims. Load-bearing claims: if this is wrong, does the whole conclusion fall apart? Conflation: is the report treating two distinct things as one? And convenience bias: are the findings suspiciously aligned with what the user wanted to hear?

Flagged claims get targeted verification queries. Each claim gets a verdict. CONFIRMED means a second source corroborates it. CORRECTED means verification found something different, and the report says so. UNVERIFIABLE means no independent confirmation could be found, and the confidence drops.

The difference sounds subtle but it changes the entire character of the output. “Find and summarise” becomes “find, verify, and flag uncertainty.” That’s the difference between a tool that feels helpful and one you can actually trust.

The third failure was operational, not intellectual. I launched a deep research run on compaction management for an agent SDK project. The skill started fine. PLAN, DIVERGE, CHALLENGE, SEARCH — all completed. TRIAGE selected the sources. Then silence. The agent entered READ and never came back.

I checked the progress file. The last entry had a timestamp from two hours ago. The agent was still technically running, but producing nothing. A single WebFetch call had hung on a URL that never responded, and since WebFetch has no timeout, it just waited. Forever (yes they implemented a webfetch tool with no timeout…).

This happened three more times over the next week. Researching Mac laptops for AI inference: stalled in READ. Cross-platform AI frameworks: stalled in READ for twelve hours before I noticed. Every time, the same pattern: the agent enters a fetch, the fetch hangs, everything downstream stops.

The fix wasn’t a single change. It was a resilience system. First, a progress protocol: the subagent writes timestamped entries at every phase transition with elapsed time and tool call counts. Second, a deadman’s switch: the dispatcher monitors the progress file on a timer and compares timestamps, not phase labels. A progress file showing “READ phase” with a two-hour-old timestamp means the agent is stuck in read, not actively reading. If two check intervals pass without a new timestamp, the agent gets killed.

Third, checkpoint recovery. When the dispatcher kills a stalled agent, it doesn’t start over. It reads the progress file to find the last completed phase, writes all accumulated results to a checkpoint file, and launches a fresh agent that resumes from that checkpoint. The fresh agent gets a clean context window, no accumulated noise from the stalled run, and picks up where the previous one left off.

I set a hard rule: maximum two recovery attempts. If the third agent stalls, something is fundamentally wrong with the research brief or the available sources, and the skill surfaces what it has so far rather than burning more credits.

This is the part that doesn’t make it into product demos. Nobody shows the deadman’s switch. Nobody talks about the agent that hung for twelve hours. But if you want research that runs autonomously — and I mean actually unattended, overnight, while you sleep — this is the work that matters. The methodology is the interesting part. The resilience is what makes it real.

Truth be told, it’s still getting stuck, but this goes into the much larger problem of LLM unreliability. Those instructions above are still nothing more than instructions in a prompt, as I’ve now said more times than I care to count, that simply cannot be trusted to run. The solution here is to turn the skill into mostly code, which is what I’m working on now.

Most research tools give you a report and a list of URLs. That’s an answer plus a bibliography. It tells you what was found but nothing about how it was evaluated, why certain sources were prioritised, or where the methodology might have gaps.

I wanted something different. Every report from the skill includes the methodology: how many queries, what search strategy, how many sources consulted versus used, whether reassessment triggered. The sources table shows reputation tier, relevance, and date. Minority views get their own section. Tensions between sources are described explicitly, with reasoning about which position seems stronger.

The dual-format output matters here too. The markdown prose is what I read. The YAML appendix is what gets fed to Claude Code or scripts for follow-up work. If I want to re-research the same topic, the appendix provides the structured prior knowledge that makes the DIFF possible.

I’ve already used this in practice with research diffs: running the competitive landscape research twice and producing a document that shows only what changed between v1 and v2. New companies discovered, expanded data on existing ones, new failure patterns identified, new analytical frameworks surfaced. That diff document is the DIFF concept applied to research itself. Not “here’s everything again,” but “here’s what’s new since last time.”

The deep research skill isn’t something I invoke once when I have a question. It’s become infrastructure.

For sure my biggest use case is exploring larger topics, but what surprised me most is how it quickly began to operate at multiple zoom levels within a single project. In the autonomous development pipeline I’ve been building (more on that in a future post), deep research fires at three tiers. At the topic level, before any specs are created, the system researches the overall problem space. When I was building an MLX inference server, the first thing that happened was broad research on MLX serving patterns, existing implementations, and known limitations.

At the change level, when the spec system creates a specific feature or change, targeted research validates the design. Before designing the Docker container setup, the system researched container venv strategies for example (I wanted to avoid duplication and leverage caching for speedier startup).

At the task group level, before implementing each chunk of code, the system researches best practices, frameworks, and libraries for that specific functionality. Before building a YouTube transcript skill, it researched yt-dlp subtitle extraction versus audio transcription approaches.

Each level is more focused than the last. The broad research constrains the specs, which constrain the implementation, which is further grounded by targeted research. And at each level, the research scans the workspace for prior research output before it starts, so it knows what previous levels already established. That’s the DIFF operating fractally: each pass focuses on what’s new relative to what’s already been researched.

This is what makes autonomous development actually work for me. The agent isn’t coding from stale training data. It’s researching current reality at every decision point. But there’s a practical problem here that I haven’t mentioned yet: the skill couldn’t run autonomously before I solved the container problem (nothing autonomous can!). I couldn’t trust it to browse the web unsupervised on my machine. Containers solved that, at least vastly reduced the attack surface. But that’s the next post.

Every piece of work I do now starts with research. Brainstorming, spec creation, implementation. The research knows what I know (through memory and checking past research) and focuses on what I don’t. It searches where things are listed, not just where they’re discussed. It seeks disagreement, not just confirmation. It verifies before it reports. And it shows its work so I can judge the process, not just the conclusion.

When it finishes, it does one more thing: it triages its own findings for anything that should become persistent knowledge. A fact about a technology’s limitations, a decision about which library to use, a market data point that matters for ongoing work. It proposes updates to my memory files. I approve or reject each one. The research loop doesn’t just produce a report. It feeds back into the system that will make the next research run smarter.

Fourteen versions. Seven weeks. Each one a response to something that went wrong. A missed startup. A confident wrong claim. An agent that hung for twelve hours. A conversation with someone building in the same space. The skill isn’t finished. There are things it still misses. There are failure modes I haven’t encountered yet.

But the principle is right. Research isn’t summarization of top N sources. It’s the difference between what you know and what you need to know. Build for the diff, and the research gets better every time you use it.