/deep-research

name: deep-research
description: "Deep research and discovery before building something new. Explores local projects for reusable code, researches competitors, reads forums and reviews, analyses plugin ecosystems, investigates technical options, and produces a comprehensive research brief. Three depths: focused (30 min), wide (1-2 hours), deep (3-6 hours). Triggers: 'research this', 'discovery', 'explore the space', 'what should I build', 'competitive analysis', 'before I start building', 'research before coding'. Not for cited fact-checking research reports (a separate harness does those); this is pre-build product discovery."
compatibility: claude-code-only

Deep Research

Comprehensive research and discovery before building something new. Instead of jumping straight into code from training data, this skill goes wide and deep — local exploration, web research, competitor analysis, ecosystem signals, future-casting — and produces a research brief that makes the actual build 10x more productive.

Depth Levels

The difference is **scope of ambition**, not just time.

| Depth | Purpose | Scope | |-------|---------|-------| | **focused** | Answer a specific question | One decision: "CodeMirror vs ProseMirror?" — targeted search, local scan, 1-2 comparisons. Produces a 1-page recommendation. | | **wide** | Understand the space | Landscape for a new product or feature. Competitors, ecosystem, user needs, architecture options. Enough to write a spec. | | **deep** | Plan a major build | Leave no stone unturned. Everything in wide PLUS library/component research, plugin ecosystems, GitHub issues mining, community sentiment, future-casting, technical deep-dives on every decision. Enough to drive weeks of coding. |

Default: **wide**

Workflow

1. Understand the Intent

Ask the user:

• **What** are you building? (one sentence)
• **Why?** What problem does it solve? Who's it for?
• **Constraints?** Stack preferences, budget, timeline, must-haves?
• **Existing work?** Any projects to build on? Repos to look at?

If the user gives a brief prompt ("obsidian replacement on cloudflare"), that's enough — fill in the gaps through research.

2. Local Exploration

Scan the user's machine for relevant prior work:

# Find related projects by name/keyword
ls ~/Documents/ | grep -i "KEYWORD"

# Read CLAUDE.md of related projects for architecture context
find ~/Documents -maxdepth 2 -name "CLAUDE.md" -exec grep -l "KEYWORD" {} \;

# Check for reusable patterns, schemas, components
find ~/Documents -maxdepth 3 -name "schema.ts" -o -name "ARCHITECTURE.md" | head -20

For each related project found:

• Read CLAUDE.md (stack, architecture, gotchas)
• Check for reusable code (schemas, components, utilities, configs)
• Note what worked well and what didn't (from git history, TODO comments)

Also check:

• Basalt Cortex (`~/Documents/basalt-cortex/`) for related clients, contacts, knowledge facts
• `grep -rl "KEYWORD" ~/Documents/basalt-cortex/ --include="*.md"`

3. Web Research

Search broadly to understand the space:

• **Product category**: "markdown note app", "knowledge management tool for teams"
• **Competitors**: find top 5-10 by searching "best X", "X alternatives", "X vs Y"
• **Open source**: search GitHub for open-source alternatives, check star counts
• **Architecture**: "how to build X", "X tech stack", "building X with [framework]"
• **Technology docs**: check llms.txt, official docs for key technologies
• **Platform examples**: "built with Cloudflare Workers", "D1 full-text search example"
• **Tutorials and case studies**: "building a Y from scratch", "lessons learned building Z"

4. Ecosystem and Community Research (wide + deep)

Go beyond the core product — the ecosystem reveals what users actually need:

**Plugins and add-ons**:

• What plugins exist for major competitors? The most popular ones reveal what the core product lacks.
• e.g. Obsidian has 1800+ plugins — the top 20 tell you what Obsidian doesn't do well natively.
• Search: "top [product] plugins", "[product] plugin directory"

**GitHub issues and feature requests**:

• Check top competitors' GitHub repos for most-upvoted issues
• Sort by thumbs-up reactions — this is direct user demand signal
• Check closed issues for how features were implemented

**Forum discussions**:

• Reddit: r/[product], r/selfhosted, r/webdev, relevant niche subreddits
• Hacker News: search for the product category
• Discord/Discourse: product-specific communities
• What do users love? What do they complain about? What do they wish existed?

**App store and review sites**:

• 1-star reviews = unmet needs (the product fails at this)
• 5-star reviews = what to preserve (users love this, don't break it)
• 3-star reviews = the interesting middle (it's okay but...)
• Search: ProductHunt, G2, Capterra, App Store reviews

**Integration requests**:

• What systems do users want to connect to? (Zapier integrations, API requests)
• These reveal real workflows — users duct-tape tools together

5. Competitor Deep-Dive (wide + deep)

For each major competitor (3-5 for wide, 5-10 for deep):

| Question | How to research | |----------|----------------| | Features | Landing page, docs, changelog | | Pricing | Pricing page, comparison sites | | User complaints | Reddit, HN, app store reviews | | Tech stack | Wappalyzer, view-source, job postings, blog posts | | What they do well | 5-star reviews, product demos | | What they do poorly | 1-star reviews, forum complaints, migration guides FROM the product | | Documentation quality | Read their docs site — is it comprehensive? What topics need the most explanation? (Complex topics = things users struggle with) | | Help/support content | Help centre, FAQ, knowledge base, support forums — what questions do users ask most? | | Onboarding/tutorials | Getting started guides, video tutorials, interactive walkthroughs — how do they teach their product? What do they assume the user already knows? | | API