deep-research

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

```bash
# 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 documentation | If they have an API — how well documented? What patterns do they use? What SDKs do they provide? |
| Migration guides | Do they have "switch from X" guides? These reveal what they consider their advantages AND what users find hard to switch from |

### 6. Library and Component Research (deep mode)

Research the building blocks — what already exists that you can use or learn from:

**React / UI libraries**:
- Search npm for category-specific packages ("react markdown editor", "react kanban", "react data table")
- Check weekly downloads, last publish date, GitHub stars, open issues count
- Read the README and examples — what patterns do they use?
- Check