Effect-TS Research Protocol

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

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

---

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