Deep Research

Comprehensive investigation that informs major decisions. Produces structured reports for stakeholders.

Integrates with:

• ohno — Creates research task, tracks progress, logs findings
• project-harness — Works within session workflow
• spike — May spawn focused spikes for specific technical questions
• Domain skills — May invoke for specialized analysis

When to Use Deep Research vs Spike

┌────────────────────────────────────────────────────────────────────────────┐
│  SPIKE (hours)                │  DEEP RESEARCH (days)                      │
├────────────────────────────────────────────────────────────────────────────┤
│  "Can we use X?"              │  "Which of X, Y, Z should we use?"         │
│  Single question              │  Multiple related questions                │
│  2-4h time box               │  1-5 days investigation                    │
│  Team/self audience           │  Stakeholder audience                      │
│  Decision + brief report      │  Comprehensive report + recommendations   │
│  PoC optional                │  Usually no code                          │
└────────────────────────────────────────────────────────────────────────────┘

Use deep-research when:

• Decision impacts architecture, budget, or team direction
• Multiple viable options need systematic comparison
• Stakeholders need comprehensive rationale
• Industry context or competitive landscape matters

Use spike instead when:

• Single yes/no question
• Technical feasibility is the only concern
• Time-boxed answer is sufficient

Research Types

See references/research-types.md for detailed type-specific guidance.

Research Workflow

┌─────────────────────────────────────────────────────────────────────────┐
│ 1. SCOPE    Define questions, criteria, constraints                     │
│       ↓                                                                  │
│ 2. GATHER   Identify sources, collect documentation, find examples      │
│       ↓                                                                  │
│ 3. ANALYZE  Compare options against criteria, identify trade-offs       │
│       ↓                                                                  │
│ 4. SYNTHESIZE  Form recommendations, document rationale                 │
│       ↓                                                                  │
│ 5. PRESENT  Structured report for stakeholders                          │
└─────────────────────────────────────────────────────────────────────────┘

Phase 1: Scope

Frame the investigation with clear boundaries:

## Research Definition

**Topic**: Authentication solutions for multi-tenant SaaS

**Primary Questions**:
1. Which auth providers support enterprise SSO + social login?
2. What are the cost implications at 10k, 100k, 1M users?
3. How complex is integration with our existing stack?

**Evaluation Criteria** (weighted):
- Enterprise features: 30%
- Developer experience: 25%
- Cost scalability: 25%
- Community/support: 20%

**Constraints**:
- Must support SAML and OIDC
- Self-hosted option preferred
- Budget: <$10k/month at scale

**Out of Scope**:
- Custom auth implementation
- Compliance certification research

Scoping Questions:

• What decision will this research inform?
• Who are the stakeholders?
• What criteria matter most?
• What constraints are non-negotiable?
• What’s explicitly out of scope?

Phase 2: Gather

Build a comprehensive source base:

Source Priority (high to low):

1. Official documentation, API references
2. Engineering blogs from adopters at scale
3. GitHub repos, sample implementations
4. Conference talks, case studies
5. Community discussions, Stack Overflow
6. Marketing materials (verify claims)

See references/source-quality.md for evaluation criteria.

Gathering Patterns:

• Start with official docs for feature matrix
• Search for “[tool] at scale” case studies
• Check GitHub issues for pain points
• Look for migration stories (to AND from)
• Find pricing calculators, estimate at your scale

Phase 3: Analyze

Compare systematically against criteria:

## Comparison Matrix: Auth Providers

| Criteria | Auth0 | Clerk | Supabase Auth | WorkOS |
|----------|-------|-------|---------------|--------|
| Enterprise SSO | ✓ All major | ✓ All major | Limited | ✓ All major |
| Social Login | ✓ Extensive | ✓ Good | ✓ Good | ✓ Good |
| Self-hosted | ✗ No | ✗ No | ✓ Yes | ✗ No |
| Pricing (100k MAU) | $2,400/mo | $1,200/mo | $0 (self) | $4,500/mo |
| Next.js Integration | Good | Excellent | Good | Good |
| **Score** | 78/100 | 85/100 | 72/100 | 80/100 |

Analysis Patterns:

• Create comparison matrix for each criterion
• Document evidence for each claim
• Note gaps in information
• Identify hidden costs, complexity
• Consider migration/lock-in implications

Phase 4: Synthesize

Form actionable recommendations:

## Synthesis

### Key Findings
1. All evaluated providers meet baseline requirements
2. Clerk offers best DX for our stack (Next.js + React)
3. Supabase Auth is cost-effective but enterprise features lag
4. Auth0 has most mature enterprise features but highest cost

### Trade-off Analysis
- **Clerk**: Best DX, good features, moderate cost
  - Risk: Smaller company, less enterprise track record
- **Auth0**: Enterprise-proven, comprehensive features
  - Risk: Cost scales aggressively, migration complexity

### Recommendation
**Primary**: Clerk for new development
**Rationale**: Best DX alignment, adequate enterprise features, competitive cost
**Contingency**: Auth0 if enterprise requirements expand significantly

Phase 5: Present

Deliver structured report:

# Research Report: Authentication Solutions

## Executive Summary
[1-2 paragraphs: context, key findings, recommendation]

## Background
[Why this research was needed, decision context]

## Methodology
[How research was conducted, sources used]

## Options Evaluated
[Brief description of each option]

## Comparison
[Matrix and detailed analysis]

## Recommendation
[Primary recommendation with rationale]

## Trade-offs & Risks
[What we're accepting with this choice]

## Follow-up Actions
[Spikes, implementation tasks, or additional research]

## Appendix
[Detailed data, sources, pricing breakdowns]

See assets/templates/research-report.md for full template.

ohno Integration

Creating Research Tasks

# Create research task
ohno add "Research: Auth solutions for multi-tenant SaaS" \
  --type research \
  --estimate 2d \
  --tags research,auth,architecture

# Track progress with subtasks
ohno add "Gather Auth0 documentation" --parent <research-id>
ohno add "Gather Clerk documentation" --parent <research-id>
ohno add "Create comparison matrix" --parent <research-id>
ohno add "Write research report" --parent <research-id>

Progress Checkpoints

Day 1: Scope defined, sources identified
Day 2: Gathering complete, analysis started
Day 3: Synthesis forming, draft report
Day 4: Report complete, review
Day 5: Finalize and present

Creating Follow-up Tasks

Research often spawns additional work:

# Spike for technical validation
ohno add "Spike: Clerk integration with our Next.js setup" --type spike

# Implementation tasks
ohno add "Implement Clerk auth integration" --type task
ohno add "Create SSO onboarding flow" --type task

Output Structure

.claude/
├── research/
│   ├── auth-solutions-2026-01-18/
│   │   ├── report.md              ← Main research report
│   │   ├── comparison-matrix.md   ← Detailed comparisons
│   │   ├── sources.md             ← Source log with notes
│   │   └── raw-notes/             ← Gathering artifacts
├── PROJECT.md
└── tasks.db

Anti-Patterns

During Scoping

During Gathering

During Synthesis

Quality Checklist

Research Definition

• Primary questions clearly stated
• Evaluation criteria weighted
• Constraints documented
• Out of scope defined
• Timeline realistic for scope

Gathering

• Multiple source types used
• Official docs reviewed
• Real-world case studies found
• Pain points researched
• Sources documented with dates

Analysis

• All options evaluated fairly
• Comparison matrix complete
• Evidence cited for claims
• Gaps in knowledge noted
• Trade-offs explicit

Synthesis

• Clear recommendation made
• Rationale documented
• Risks acknowledged
• Alternatives noted
• Follow-up actions defined

Presentation

• Executive summary present
• Appropriate depth for audience
• Sources cited
• Appendix with details
• Report filed in .claude/research/

References

• references/research-types.md — Detailed guidance per research type
• references/source-quality.md — Evaluating source quality
• references/synthesis-patterns.md — Forming recommendations
• assets/templates/research-report.md — Full report template
• assets/templates/comparison-matrix.md — Matrix template