---
name: kb-workflow
description: "Use before starting any non-trivial task to search the knowledge base for context, and after completing work to capture findings. Teaches the token-efficient retrieval pattern and self-learning loop."
---

# Knowledge Base Workflow

## What This Skill Does

This skill teaches you how to use the knowledge-base-server MCP tools efficiently. It does NOT replace the MCP server — it complements it by giving you the retrieval strategy that saves 90%+ tokens.

Think of it this way:
- **MCP server** = the engine (search, read, write, capture)
- **This skill** = the driving instructions (when to search, what to read, how to capture)

## Before Starting Any Task

Search the KB for relevant context BEFORE writing code or making decisions:

```
1. kb_context("topic") — get summaries only (~100 tokens per doc, 90% savings)
2. Review titles and summaries — decide which docs matter
3. kb_read(id) — read full content ONLY for docs you actually need
```

Never skip this. The KB has accumulated lessons, fixes, decisions, and architecture docs. Searching first prevents:
- Repeating solved problems
- Contradicting past decisions
- Missing known pitfalls
- Wasting tokens on re-discovery

## The Three-Tier Retrieval Pattern

The KB has three tiers of information. Query the right tier for your need:

| Need | Tool | Tokens | When |
|------|------|--------|------|
| Quick context | `kb_context` | ~100/doc | Always start here |
| Specific search | `kb_search` | ~200/result | Looking for something specific |
| Conceptual match | `kb_search_smart` | ~200/result | Fuzzy/semantic queries |
| Full document | `kb_read` | ~500-5000/doc | Only after context confirms relevance |

**Rule: Never kb_read without kb_context first.** You wouldn't read an entire book to check if it's relevant — you'd read the summary.

## After Completing Work

Capture what you learned so the next session starts smarter:

### After debugging sessions:
```
kb_capture_session:
  goal: "What you were trying to do"
  commands_worked: "What worked"
  commands_failed: "What failed and why"
  root_causes: "The actual problem"
  fixes: "What fixed it"
  lessons: "What to do differently next time"
```

### After bug fixes:
```
kb_capture_fix:
  title: "Short fix title"
  symptom: "What was broken"
  cause: "Root cause"
  resolution: "How it was fixed"
```

### After research or decisions:
```
kb_write:
  title: "Decision or finding title"
  type: "decision" or "research" or "lesson"
  content: "What was decided and why"
```

## The Self-Learning Loop

This is how the system compounds intelligence:

```
Session N:
  1. Search KB for context (maybe find nothing)
  2. Do the work (hit problems, make decisions)
  3. Capture findings to KB

Session N+1:
  1. Search KB for context (find Session N's captures!)
  2. Skip the problems Session N already solved
  3. Capture NEW findings

Session N+100:
  1. Search KB for context (find 100 sessions of accumulated knowledge)
  2. One-shot clean implementation because context covers everything
  3. Capture only genuinely new learnings
```

This is NOT fine-tuning. The model doesn't change. The context it receives improves. And context is everything.

## When to Use Each Tool

| Situation | Tool | Why |
|-----------|------|-----|
| Starting a new task | `kb_context` | Get the lay of the land |
| "How did we do X?" | `kb_search` | Find specific past work |
| "What do we know about X?" | `kb_search_smart` | Conceptual/fuzzy match |
| Need full implementation details | `kb_read` | After context identified the doc |
| Finished debugging | `kb_capture_session` | Record what happened |
| Fixed a bug | `kb_capture_fix` | Record symptom/cause/fix |
| Made a decision | `kb_write` type=decision | Record the decision and why |
| Found useful research | `kb_write` type=research | Save for future reference |
| Want cross-cutting insights | `kb_synthesize` | Connect dots across sources |
| New content needs tagging | `kb_classify` | Auto-classify unprocessed notes |

## What NOT to Do

- Don't `kb_read` every document that matches a search — read summaries first
- Don't skip searching because "I probably know this" — the KB knows more than you remember
- Don't forget to capture after significant work — a lesson not captured is a lesson repeated
- Don't index raw code into the KB — use CODEMAP.md structural maps instead
- Don't treat the KB as a dump — classified, typed, tagged notes are 10x more useful than raw text