knowledge-architecture

Files (1)

• SKILL.md

SKILL.md (first lines)

# Knowledge Architecture

Separate three decisions people often mash together: **who consumes**, **what form**, **how retrieval works**.

## Step 1 — Who consumes?

| Consumer | Optimize for |
|----------|----------------|
| **Humans** | Readable structure, navigation, editability (Wiki / Markdown tree) |
| **Agents** | Chunkability, metadata, stable IDs, tool-friendly retrieval |
| **Both (default for products)** | Single source of truth humans edit + indexes agents query |

Default bias: **coexistence** — humans write Markdown/Wiki; agents get hybrid retrieval over the same source. Avoid a second shadow knowledge base unless required.

## Step 2 — What form?

| Form | When |
|------|------|
| **Markdown / Wiki** | Most products; docs, runbooks, specs |
| **Structured DB records** | Strong schema entities (tickets, SKUs) |
| **Knowledge graph** | Relationships are first-class (org charts, law cites, multi-hop entity links) |
| **Vector-only corpus** | Large unstructured dump with weak structure needs |

MVP default: **Markdown wiki (or `/docs`)**. Promote to graph when queries are relationship-heavy and hybrid RAG fails.

## Step 3 — Retrieval pattern

| Pattern | When |
|---------|------|
| Full-text only | Small corpus, precise keywords |
| Vector RAG | Semantic questions over unstructured text |
| **Hybrid** (keyword + vector) | Default production RAG |
| **Agentic RAG** | Multi-step: plan → retrieve → critique → retrieve again |
| Graph RAG | Multi-hop entity/relation questions |

MVP default: **hybrid retrieval**. Use agentic RAG when single-shot retrieval quality is measurably insufficient.

## Decision Output

```markdown
## Consumers: human | agent | both
## Source form: markdown-wiki | db | graph | mixed
## Retrieval: fts | vector | hybrid | agentic | graph-rag
## Ingestion path
## Evaluation plan (5 real questions the system must answer)
## Non-goals
```

## Anti-Patterns

- "We need a knowledge graph" with no multi-hop questions
- Separate Notion for humans + random vectors for agents with no sync
- Agentic RAG theater on a 20-page corpus
- Building custom RAG platform instead of using mature components (research-before-build)

## Related

- `research-before-build`, `stack-defaults`
- `references/knowledge-decision-tree.md`

From AVIDS2/avid-skill, MIT.

More from AVIDS2/avid-skill