Knowledge architecture

Tag Registry and RAG flow

RAG is useful for retrieval and suggestion, but the source of truth should stay in structured wiki notes, Skill Cards, and a controlled tag registry.

Do not dump everything into a vector database. Build a clean knowledge layer first, then use RAG as the retrieval layer on top.

The full flow

Raw Sources / Build Logs: immutable input and ground truth.

Curated Wiki Notes: human-readable synthesis and reusable principles.

Skill Cards: executable knowledge with trigger, rule, steps, checks, source project, anti-patterns, and tags.

Tag Registry: controlled vocabulary for source project, tech, skill type, workflow stage, artifact type, status, and maturity.

Embedding Index / RAG: retrieval layer that uses text similarity plus tag metadata filters.

Query / Suggest / Auto Skill Recall: user asks a question or enters a project context, then the system recalls relevant Skill Cards.

Tags should have ids like `tech:vite`, `project:jiju`, `skill-type:ux-feedback`, not loose hashtags.

Each tag needs label, type, aliases, description, parent, status, and optional replacement.

Tags classify and filter. They should not replace the actual skill content.

Retire or merge duplicate tags instead of letting the registry drift.

RAG can answer questions like: have I solved a similar Vite build problem before?

RAG can recommend skills when a new project context matches old triggers.

RAG can help extract draft Skill Cards from build logs, bug fixes, and wiki notes.

The vector database should not be the source of truth. It should be regenerated from structured cards and notes.

Start with `/wiki`, `/wiki/skills`, `/tag-registry`, and `/skill-cards` as structured data.

Normalize tags before embedding content.

Embed Skill Card fields and use tags as metadata filters.

Return source links with every answer so the user can inspect the original note.

Keep every generated skill in draft until reviewed.