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.
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:
- Admit uncertainty explicitly
- Research via authoritative sources
- 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
# 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
- website - Human-authored, battle-tested prose
- effect/packages/*/test/ - Canonical test patterns
- effect-atom/packages/atom/test/ - Atom-specific patterns
- 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:
- Explicit uncertainty: "I'm not sure if...", "Is this correct?"
- API questions: "What's the current way to...", "How do I..."
- Pattern validation: "Am I doing this right?", "Best practice for..."
- Version concerns: "Has this changed?", "Current version of..."
- Before implementation: Any significant code writing involving external APIs
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?