Effect-TS Research Protocol

Purpose: Specialized research workflow for Effect-TS, effect-atom, and related ecosystem. Ensures verified patterns before implementation.

Quick Start: Research Workflow

┌─────────────────────────────────────────────────────────────────┐
│  EFFECT RESEARCH WORKFLOW                                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. ADMIT UNCERTAINTY                                            │
│     "My Effect knowledge is from May 2025..."                    │
│                                                                  │
│  2. QUERY DEEPWIKI (Verification Style)                          │
│     "Is [PATTERN] still correct for [USE CASE]?"                 │
│     Repos: Effect-TS/effect, tim-smart/effect-atom               │
│                                                                  │
│  3. CROSS-REFERENCE SUBMODULES                                   │
│     ../../submodules/website/  → Human docs (priority)           │
│     ../../submodules/effect/   → Test patterns                   │
│     ../../submodules/effect-atom/ → Atom patterns                │
│                                                                  │
│  4. CHECK CODEBASE PRECEDENT                                     │
│     .edin/EFFECT_PATTERNS.md                                     │
│     src/lib/*/  → Working implementations                        │
│                                                                  │
│  5. IMPLEMENT WITH CONFIDENCE                                    │
│     [VERIFIED] pattern from step 2-4                             │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

deepwiki Queries for Effect

Available Repos

Effect-TS/effect

tim-smart/effect-atom

Query Patterns

Service Definition:

mcp__deepwiki__ask_question
  repoName: "Effect-TS/effect"
  question: "What is the current recommended pattern for defining Effect
             services with Effect.Service<>()? I believe it uses
             double-parenthesis syntax. Is this still accurate?"

Schema Patterns:

mcp__deepwiki__ask_question
  repoName: "Effect-TS/effect"
  question: "For discriminated unions, should I use Schema.TaggedStruct
             or Schema.TaggedClass? When would I choose one over the other?"

Atom Integration:

mcp__deepwiki__ask_question
  repoName: "tim-smart/effect-atom"
  question: "What is the correct way to use Atom.runtime with Effect
             services? I want to create operation atoms that can yield
             services from a Layer."

Stream Patterns:

mcp__deepwiki__ask_question
  repoName: "Effect-TS/effect"
  question: "Is Stream.fromQueue still the recommended way to create
             streams from async sources? What about backpressure handling?"

Submodule Deep Dives

Website Submodule (Human-Authored Docs)

Location:

../../submodules/website/content/src/content/docs/docs/

Key Directories:

docs/
├── introduction/        # Getting started
├── guides/              # Best practices
├── concurrency/         # Fibers, Queue, Semaphore
├── state-management/    # Ref, SynchronizedRef
├── stream/              # Stream creation, transformation
├── schema/              # Schema definition, validation
└── additional-resources/ # Migration, myths

Common Queries:

# Find service documentation
find ../../submodules/website -name "*.mdx" | xargs grep -l "Effect.Service"

# Find schema documentation
cat ../../submodules/website/content/src/content/docs/docs/schema/*.mdx

# Find state management docs
ls ../../submodules/website/content/src/content/docs/docs/state-management/

Effect Submodule (Test Patterns)

Location:

../../submodules/effect/packages/

Key Test Directories:

packages/
├── effect/test/           # Core Effect tests
├── sql-sqlite-bun/test/   # SQLite integration (modern patterns)
├── sql-drizzle/test/      # Drizzle ORM patterns
├── platform/test/         # Platform services
└── experimental/test/     # EventLog, DevTools

Common Queries:

# Find service test patterns
grep -r "Effect.Service" ../../submodules/effect/packages/*/test/

# Find SQL transaction patterns
grep -r "transaction" ../../submodules/effect/packages/sql-sqlite-bun/test/

# Find Stream test patterns
find ../../submodules/effect/packages/effect/test -name "*Stream*"

effect-atom Submodule (Atom Patterns)

Location:

../../submodules/effect-atom/packages/atom/

Key Files:

packages/atom/
├── src/Atom.ts           # Atom implementation
├── src/Registry.ts       # Registry implementation
├── test/Atom.test.ts     # Atom test patterns
├── test/Result.test.ts   # Result handling
└── test/AtomRpc.test.ts  # RPC patterns

Common Queries:

# Atom test patterns
cat ../../submodules/effect-atom/packages/atom/test/Atom.test.ts

# Registry patterns
grep -r "Registry.make" ../../submodules/effect-atom/packages/atom/test/

# React integration
cat ../../submodules/effect-atom/packages/atom-react/src/index.ts

Research Templates by Topic

Topic: Service Definition

## Research: Effect Service Definition

**Question**: What's the current pattern for Effect.Service<>()?

**Step 1: deepwiki Verification**

mcp__deepwiki__ask_question repoName: "Effect-TS/effect" question: "I believe Effect.Service<MyService>()('id', { effect, dependencies }) is the current syntax. Is this accurate? Has anything changed regarding service definition in recent versions?"

**Step 2: Submodule Cross-Reference**
```bash
# Check website docs
grep -r "Effect.Service" ../../submodules/website/content/src/content/docs/

# Check test patterns
grep -r "Effect.Service" ../../submodules/effect/packages/sql-sqlite-bun/test/

Step 3: Codebase Precedent

grep -r "Effect.Service" src/lib/*/
cat .edin/EFFECT_SERVICE_PATTERNS.md

### Topic: Schema Definition

```markdown
## Research: Schema Patterns

**Question**: TaggedStruct vs TaggedClass - when to use which?

**Step 1: deepwiki Verification**

mcp__deepwiki__ask_question repoName: "Effect-TS/effect" question: "When should I use Schema.TaggedStruct vs Schema.TaggedClass? My understanding: TaggedStruct for pure data, TaggedClass when I need methods. Is this correct?"

**Step 2: Submodule Cross-Reference**
```bash
cat ../../submodules/website/content/src/content/docs/docs/schema/*.mdx
grep -r "TaggedStruct\|TaggedClass" ../../submodules/effect/packages/effect/src/Schema.ts

### Topic: Atom + React Integration

```markdown
## Research: Atom.runtime Pattern

**Question**: How do I create operation atoms with Atom.runtime?

**Step 1: deepwiki Verification**

mcp__deepwiki__ask_question repoName: "tim-smart/effect-atom" question: "What's the correct way to use Atom.runtime.fn() to create operation atoms that can yield Effect services? I want to compose a Layer and create callable atoms."

**Step 2: Submodule Cross-Reference**
```bash
cat ../../submodules/effect-atom/packages/atom/test/Atom.test.ts
grep -r "runtime" ../../submodules/effect-atom/packages/atom/src/

Step 3: Codebase Precedent

grep -r "Atom.runtime\|runtimeAtom" src/lib/*/atoms/
cat src/lib/slider/atoms/index.ts

### Topic: Stream Patterns

```markdown
## Research: Effect Streams

**Question**: Creating streams from async sources with backpressure

**Step 1: deepwiki Verification**

mcp__deepwiki__ask_question repoName: "Effect-TS/effect" question: "What's the recommended way to create Effect Streams from async sources like WebSockets? I'm considering Stream.async and Stream.fromQueue. Which handles backpressure better?"

**Step 2: Submodule Cross-Reference**
```bash
cat ../../submodules/website/content/src/content/docs/docs/stream/*.mdx
find ../../submodules/effect/packages/effect/test -name "*Stream*" | xargs head -50

---

## Verification Checklist

Before implementing any Effect pattern:

### Service Patterns
- [ ] Verified Effect.Service<>() syntax via deepwiki
- [ ] Checked submodule test for working example
- [ ] Confirmed dependencies array behavior
- [ ] Verified `.Default` layer generation

### Schema Patterns
- [ ] Verified Schema.* function exists in current API
- [ ] Checked for transform/encode/decode behavior
- [ ] Confirmed branded type syntax
- [ ] Verified with Schema.is runtime check

### Atom Patterns
- [ ] Verified Atom.runtime API via deepwiki
- [ ] Checked effect-atom tests for pattern
- [ ] Confirmed Registry.make() usage
- [ ] Verified React hook compatibility

### Layer Patterns
- [ ] Verified Layer composition functions
- [ ] Checked Layer.mergeAll, Layer.provide order
- [ ] Confirmed dependency resolution
- [ ] Tested with Effect.runPromise

---

## Common Pitfalls

### ❌ Assuming Effect.Ref for React State

```typescript
// WRONG - Don't use Ref when React consumes state
const stateRef = yield* Ref.make(initial)

Correct: Use Atom.make() when React is the consumer

❌ Single-parenthesis Effect.Service

// WRONG
class MyService extends Effect.Service<MyService>("id", {}) {}

// CORRECT (double parenthesis)
class MyService extends Effect.Service<MyService>()("id", {}) {}

❌ Missing

as const

on service returns

// WRONG
return { method }

// CORRECT
return { method } as const

❌ Trusting cached mental models

// WRONG
"I know how Effect.Service works..."

// CORRECT
[UNCERTAIN] Let me verify the current Effect.Service API...

Integration with Other Skills

/effect-service-authoring

/effect-schema-mastery

/effect-atom-integration

/effect-stream-patterns

/effect-match-patterns

Quick Commands

# Research service patterns
mcp__deepwiki__ask_question repoName="Effect-TS/effect" question="Effect.Service current API"

# Research atom patterns
mcp__deepwiki__ask_question repoName="tim-smart/effect-atom" question="Atom.runtime usage"

# Cross-reference website docs
find ../../submodules/website -name "*.mdx" | xargs grep -l "TOPIC"

# Cross-reference test patterns
find ../../submodules/effect/packages -name "*.test.ts" | xargs grep -l "TOPIC"

# Check codebase precedent
grep -r "PATTERN" src/lib/*/
cat .edin/EFFECT_PATTERNS.md