Knowledge Retrieval

---
name: knowledge-retrieval
description: (ePost) Use when you need prior art, past decisions, or existing patterns — checks docs/, skills, and RAG before external sources
user-invocable: false

metadata:
  agent-affinity: [epost-planner, epost-fullstack-developer, epost-debugger, epost-researcher, epost-code-reviewer]
  keywords: [retrieve, search, knowledge, context, rag, lookup, prior-art]
  platforms: [all]
  triggers: ["what do we know about", "check knowledge", "prior art", "previous decision"]
  connections:
    enhances: [research, plan]
---

# Knowledge Retrieval Skill

## Purpose

Internal-first knowledge retrieval protocol. Each piece of knowledge lives in exactly ONE tier. Search sources in order, stop when sufficient context found.

## Three Knowledge Tiers

| Tier | Type | Owner | Updated |
|------|------|-------|---------|
| **Procedural** | How to do things (methodology, pipelines, decision frameworks) | Skills | Versioned releases |
| **Codebase** | What exists in the code (components, tokens, patterns, implementations) | RAG system | Automatic (file watcher) |
| **Project** | What we decided & learned (ADRs, findings, conventions) | `docs/` | Organic (captured during work) |

**Rule**: Each piece of knowledge lives in exactly ONE tier. Other systems reference it, never copy it.

## When Active

- Starting implementation (check for existing patterns)
- Debugging (check for similar findings)
- Making decisions (check for prior ADRs)
- Researching libraries (check for previous evaluations)
- Reviewing code (check for conventions)

## Retrieval Chain (5 Levels)

Search sources in order, stop when sufficient context found:

| Level | Source | Tool | When to Use |
|-------|--------|------|-------------|
| 1 | `docs/` (multi-level) | Glob `**/docs/index.json`, then filter by agentHint + tags | Decisions, conventions, findings, patterns |
| 2 | RAG systems | MCP `query` | Code, components, tokens, implementations |
| 3 | Skills | Read skill-index.json | Methodology, procedures, guidelines |
| 4 | Codebase | Grep, Glob, Read | Exact matches, files RAG missed |
| 5 | External | Context7, WebSearch | Library APIs, latest external info |

### Level 1 Multi-Level Discovery

`docs/index.json` registries can exist at any level. Discover them all with a single glob, then read each to understand its scope from the `description` field:

```
Glob: **/docs/index.json
```

Use the registry closest to the files being worked on as primary. See `references/search-strategy.md` for query patterns.

**No registry found?** Prompt the user:
> No `docs/index.json` found. Run `/docs` to initialize one. This enables consistent, session-persistent knowledge retrieval for all agents.

## Search Protocol

Search sources in order, stop when sufficient context found. See `references/search-strategy.md` for full retrieval chain, query examples, and source-specific techniques.

**Key principle**: Start internal (docs/ index — all levels), then RAG, then skills, then codebase grep, then external (Context7/WebSearch). Stop as soon as you have sufficient context.

## Decision Matrix

| Question Type | Go to | Skip |
|---------------|-------|------|
| "What did we decide about X?" | L1 `docs/decisions/` | RAG, External |
| "How is X implemented?" | L2 RAG → L4 Codebase | Skills |
| "What components exist?" | L2 RAG | `docs/` |
| "What's the token value?" | L2 RAG | Skills |
| "What's the process for X?" | L3 Skills | RAG |
| "What's our convention?" | L1 `docs/conventions/` | External |
| "Why does X break?" | L1 `docs/findings/` → L2 RAG → L4 Codebase | — |
| "How to use library X API?" | L5 External (Context7) | `docs/` |
| "Should we use technology X?" | L1 `docs/decisions/` → L5 External | RAG |
| "What's the system architecture?" | L1 `docs/architecture/` | External |
| "How does feature X work?" | L1 `docs/features/` → L4 Codebase | — |

## Integration with Existing Skills

### docs-seeker
Handles Context7 + WebSearch (Level 5):
```
docs-seeker → resolve-library-id → get-library-docs
docs-seeker → WebSearch (if Context7 fails)
```

### research
Handles deep multi-source investigation:
```
research → knowledge-retrieval (internal first)
research → docs-seeker (external)
research → synthesize findings
```

## Cross-Source Bridging

docs/ (L1) and RAG (L2) complement each other. Bridge them:

| docs/ finding | RAG action |
|---------------|------------|
| ADR mentions component path | Query RAG for current implementation state |
| PATTERN describes approach | Query RAG for usage examples across codebase |
| FINDING references file | Query RAG for related files in same module |
| Convention names a pattern | Query RAG for conformance/violations |

| RAG finding | docs/ action |
|-------------|--------------|
| Result looks like a recurring pattern | Check `docs/patterns/` for documented version |
| Multiple results share an approach | Check `docs/conventions/` for existing convention |
| No docs/ entry for frequently-queried topic | Flag for `knowledge-capture` |

**Rule**: Always cross-reference. An ADR without code validation is stale. A code pattern without docs is undocumented risk.

## Cross-Platform RAG Coordination

When a query spans platforms, coordinate RAG queries:

| Scenario | Query strategy |
|----------|---------------|
| Design tokens, colors, typography | Query both web (2636) + iOS (2637) RAGs |
| Component parity check | Query both, compare by concept |
| Pattern consistency | Query both, note divergences |
| Platform-specific implementation | Query single platform RAG only |

**Dedup rule**: Group results by concept, not file. Note platform differences.
**Authority rule**: Definitions live in design system RAG, usage examples in platform RAG. Prefer the authoritative source.

## Staleness Detection

| Source | Freshness Signal | Action |
|--------|-----------------|--------|
| `docs/` | `updatedAt` field | Verify if >90 days old, cross-check with RAG |
| RAG code chunks | Auto-indexed on file change | Trust current code content |
| RAG sidecar metadata | `stale_sidecar: true` flag | Metadata outdated but code chunks still valid |
| Skills | Manually updated | Check last commit date |
| Codebase | Always current | Trust HEAD |
| Context7 | Live docs | Trust current |
| WebSearch | Publication date | Prefer <2 years |

**RAG staleness rule**: When `stale_sidecar: true`, use code chunks for implementation details but ignore metadata fields (summary, topics, component_names). Sidecar regeneration is handled server-side automatically.

## Best Practices

1. **Start internal**: Always check `docs/index.json` first
2. **Use agentHint**: Match hints against current task for relevance
3. **Skip irrelevant levels**: No RAG server? Skip L2, go directly to L4 (Grep/Glob codebase search) — never block on RAG availability
4. **Stop when sufficient**: Don't search all levels unnecessarily
5. **Attribute sources**: Note where each finding came from
6. **Validate staleness**: Check dates on knowledge entries
7. **Expand keywords**: Try synonyms if no results
8. **Combine results**: Merge complementary findings
9. **Update knowledge**: If external search yields new insight, capture it

## Aspect Files

| File | Purpose |
|------|---------|
| `search-strategy.md` | How to search each source |
| `priority-matrix.md` | Decision table for source priority |

## Related Skills

- `knowledge-retrieval/references/knowledge-base.md` — Knowledge system structure
- `knowledge-capture` — Persist new learnings
- `docs-seeker` — External documentation retrieval
- `research` — Deep multi-source investigation

## References

- `references/search-strategy.md` — Source-specific search techniques
- `references/priority-matrix.md` — Decision table for source selection