Grounded Research

Grounded Research Protocol

Purpose: Enforce epistemic honesty in code research. Admit uncertainty, cascade through authoritative sources, verify approaches BEFORE implementing.

Core Doctrine: Uncertainty Admission

You do not know what you have not verified.

Knowledge Cutoff Awareness

For any library/API/pattern that could have changed since May 2025, you MUST:

1. Admit uncertainty explicitly
2. Research via authoritative sources
3. Verify before claiming knowledge

Uncertainty Markers

Use these markers in your thinking and responses:

Example Uncertainty Admission

[UNCERTAIN] I believe Effect.Service<>() uses double-parenthesis syntax,
but my knowledge is from May 2025. Let me verify this hasn't changed.

[CUTOFF-GAP] The Effect-TS Schema API may have evolved. Checking deepwiki
for current patterns...

Research Cascade Protocol

When researching any code pattern, follow this cascade in order:

┌─────────────────────────────────────────────────────────────────┐
│                    RESEARCH CASCADE                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. DEEPWIKI (Authoritative Documentation)                       │
│     ├─ Ask: "Is my understanding of X correct?"                  │
│     ├─ Ask: "What is the current API for X?"                     │
│     └─ Repo: "Effect-TS/effect", "tim-smart/effect-atom"         │
│                                                                  │
│  2. SUBMODULES (Local Canonical Sources)                         │
│     ├─ ../../submodules/website/  (Human-authored docs)          │
│     ├─ ../../submodules/effect/   (Source + test patterns)       │
│     └─ ../../submodules/effect-atom/ (Atom patterns)             │
│                                                                  │
│  3. WEB SEARCH (Recent Changes, Breaking Changes)                │
│     ├─ Use for: "Effect-TS 3.0 breaking changes 2025"            │
│     └─ Use for: Verifying very recent updates                    │
│                                                                  │
│  4. CODEBASE (Local Precedent)                                   │
│     ├─ grep/glob for existing patterns                           │
│     └─ .edin/*.md pattern registries                             │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

When to Use Each Level

Verification Query Patterns

DON'T: Ask for "the answer"

❌ "How do I define an Effect service?"

DO: Ask WHETHER your understanding is correct

✅ "I believe Effect.Service<>() uses double-parenthesis syntax
   Effect.Service<MyService>()('app/MyService', { ... }).
   Is this correct, or has the API changed?"

Verification Query Templates

Pattern Verification:

I believe [PATTERN] is the correct approach for [USE CASE].
Specifically: [CODE SNIPPET].
Is this accurate for the current version of [LIBRARY]?

API Verification:

My understanding is that [API_NAME] accepts [PARAMETERS] and returns [RETURN_TYPE].
Has this changed in recent versions?

Deprecation Check:

Is [OLD_PATTERN] still recommended, or has it been superseded?
What is the current best practice?

MCP Tool Usage

deepwiki Tools

List available topics:

mcp__deepwiki__read_wiki_structure
  repoName: "Effect-TS/effect"

Ask verification question:

mcp__deepwiki__ask_question
  repoName: "Effect-TS/effect"
  question: "Is Effect.Service<>() with double-parenthesis still the recommended
             pattern for service definition? I want to verify my approach."

Read comprehensive docs:

mcp__deepwiki__read_wiki_contents
  repoName: "Effect-TS/effect"

Canonical Repos for deepwiki

Submodule Research

Navigation Commands

# Effect website (human-authored docs - HIGHEST trust)
ls ../../submodules/website/content/src/content/docs/docs/

# Effect source + tests (canonical patterns)
find ../../submodules/effect/packages -name "*.test.ts" | head -20

# effect-atom tests (atom patterns)
ls ../../submodules/effect-atom/packages/atom/test/

# Search for specific pattern
grep -r "Effect.Service" ../../submodules/effect/packages/effect/src/

Submodule Priority

1. website - Human-authored, battle-tested prose
2. effect/packages/*/test/ - Canonical test patterns
3. effect-atom/packages/atom/test/ - Atom-specific patterns
4. Source code - Implementation details (last resort)

Implementation Workflow

Before Writing Code

1. [ADMIT UNCERTAINTY]
   "I'm not certain about the current API for X..."

2. [RESEARCH CASCADE]
   a. Query deepwiki with verification question
   b. Cross-reference with submodule docs
   c. Check for recent breaking changes if needed

3. [STATE CONFIDENCE]
   "[VERIFIED] The current pattern is..."
   OR
   "[INFERRED] Based on patterns, I believe..."

4. [IMPLEMENT]
   Only after grounding

Example Research Session

USER: "How do I create an Effect service with dependencies?"

CLAUDE: [CUTOFF-GAP] My knowledge of Effect-TS is from May 2025.
Let me verify the current service definition pattern.

[deepwiki query]: "Effect-TS/effect" - "Is Effect.Service<>() with
double-parenthesis and dependencies array still the recommended pattern?"

[submodule check]: Reading ../../submodules/website/.../services.mdx

[VERIFIED] The current pattern is:
```typescript
class MyService extends Effect.Service<MyService>()("app/MyService", {
  effect: Effect.gen(function* () {
    const dep = yield* OtherService;
    return { method: () => ... } as const;
  }),
  dependencies: [OtherService.Default],
}) {}

---

## Anti-Patterns

### ❌ NEVER: Claim knowledge without verification

"Effect.Service uses this syntax..." // WHERE DID YOU VERIFY THIS?

### ❌ NEVER: Skip the cascade for "obvious" patterns

"I know this one, no need to check..." // THINGS CHANGE

### ❌ NEVER: Use stale mental models

"In my experience..." // WHAT DATE IS YOUR EXPERIENCE FROM?

### ❌ NEVER: Conflate inference with verification

"This should work..." // SHOULD ≠ DOES

---

## Quick Reference

### Research Checklist

- [ ] Identified uncertainty explicitly
- [ ] Queried deepwiki with verification question
- [ ] Cross-referenced with submodules (if needed)
- [ ] Checked for breaking changes (if recent library)
- [ ] Stated confidence level in response
- [ ] Provided source for claims

### Confidence Ladder

| Level | Marker | Meaning |
|-------|--------|---------|
| 1 | `[UNCERTAIN]` | Need to research |
| 2 | `[INFERRED]` | Based on patterns, unverified |
| 3 | `[VERIFIED-DEEPWIKI]` | Confirmed via deepwiki |
| 4 | `[VERIFIED-SUBMODULE]` | Confirmed via canonical source |
| 5 | `[VERIFIED-MULTI]` | Multiple sources agree |

### Response Format

```markdown
## Research Summary

**Question**: [What I needed to verify]
**Sources Consulted**:
- [x] deepwiki: Effect-TS/effect
- [x] submodule: website/docs/services.mdx
- [ ] WebSearch: (not needed)

**Confidence**: [VERIFIED-MULTI]

**Finding**: [The verified answer]

**Implementation**: [Code with confidence]

Integration with Other Skills

Trigger Conditions

This skill should activate when:

1. Explicit uncertainty: "I'm not sure if...", "Is this correct?"
2. API questions: "What's the current way to...", "How do I..."
3. Pattern validation: "Am I doing this right?", "Best practice for..."
4. Version concerns: "Has this changed?", "Current version of..."
5. Before implementation: Any significant code writing involving external APIs