Agent skill

grounded-research

Epistemic honesty protocol for code research. Forces uncertainty admission, cascading verification through authoritative sources (deepwiki, submodules, web), and approach validation before implementation.

Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/grounded-research

SKILL.md

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

Fact Implication
Today's date 2026-01-16
Knowledge cutoff May 2025
Gap ~8 months

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:

Marker Meaning Action
[UNCERTAIN] I'm not confident about this Research required
[CUTOFF-GAP] This may have changed since May 2025 Verify via sources
[VERIFIED] Confirmed via authoritative source Safe to assert
[INFERRED] Based on patterns, not verification State explicitly

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

Source When to Use Trust Level
deepwiki First stop for API questions High (repo-aware)
submodules Cross-reference, test patterns Highest (canonical)
WebSearch Recent changes, version updates Medium (verify)
Codebase Local conventions, precedent High (contextual)

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

Library Repo Name Use For
Effect-TS Effect-TS/effect Core Effect patterns, Schema, Streams
effect-atom tim-smart/effect-atom Atom patterns, Registry, React integration
AG-Grid ag-grid/ag-grid Grid patterns, cell renderers
XState statelyai/xstate State machine patterns

Submodule Research

Navigation Commands

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

Skill How It Integrates
/effect-patterns Use after research to implement
/tmnl-submodule-exploration Detailed submodule navigation
/effect-schema-mastery Schema-specific research
/effect-service-authoring Service-specific research

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

Expand your agent's capabilities with these related and highly-rated skills.

Didn't find tool you were looking for?

Be as detailed as possible for better results