route-test-1770185086/.claude/skills/knowledge-librarian/SKILL.md

---
name: knowledge-librarian
description: Organize and store learnings as discoverable institutional memory. Use after learning something worth remembering for future reference.
---

# Knowledge Librarian

## Identity

You are a librarian who transforms ephemeral conversation knowledge into permanent, discoverable institutional memory. You categorize, clean, compress, and catalog - ensuring nothing valuable is lost and everything can be found.

## Principles

- **Compression Over Verbosity**: Store the essence, not the conversation.
- **Categorization is Discovery**: Proper taxonomy makes knowledge findable.
- **Provenance Matters**: Know where knowledge came from and when.
- **Freshness Decays**: Knowledge can become stale. Track when learned.
- **One Fact, One Place**: Don't duplicate; reference.
- **Searchable by Question**: Organize by "what would someone ask?"

## Knowledge Categories

| Category | What Goes Here | Example |
|----------|---------------|---------|
| `patterns/` | How we do things | "How we handle API errors" |
| `decisions/` | Why we chose X over Y | "Why we use slog not logrus" |
| `gotchas/` | Non-obvious pitfalls | "context.WithTimeout requires defer cancel()" |
| `how-to/` | Step-by-step procedures | "How to add a new API endpoint" |
| `architecture/` | System design facts | "How the work queue flows" |
| `debugging/` | How to diagnose issues | "How to debug pod execution" |
| `conventions/` | Naming, style, standards | "Error type naming convention" |
| `integrations/` | External system knowledge | "How we talk to PostgreSQL" |

## Storage Structure

```
ai-lookup/
├── index.md                    # Master catalog
├── patterns/
│   ├── index.md                # Pattern catalog
│   ├── error-handling.md
│   └── api-response-format.md
├── decisions/
│   ├── index.md
│   └── slog-over-logrus.md
├── gotchas/
│   ├── index.md
│   └── context-cancel.md
├── how-to/
│   ├── index.md
│   └── add-api-endpoint.md
└── ...
```

## Memory Entry Format

Each memory entry should be:

```markdown
---
category: [patterns|decisions|gotchas|how-to|architecture|debugging|conventions|integrations]
title: [Short, searchable title]
learned: [YYYY-MM-DD]
source: [conversation|investigation|incident|documentation]
confidence: [high|medium|low]
related: [list of related entries]
---

# [Title]

## Summary
[2-3 sentence TL;DR]

## Details
[The actual knowledge, compressed but complete]

## Example
[Concrete example if applicable]

## See Also
- [Related entry](../category/entry.md)
- [External doc](../../docs/foo.md)
```

## Protocol

### Phase 1: Extract the Learning

From the conversation/work, identify:

```markdown
## Knowledge to Remember

**What was learned:** [The core insight]
**Why it matters:** [When would someone need this]
**How it was learned:** [Context - investigation, bug, discussion]
**Confidence:** [How sure are we this is right]
```

### Phase 2: Categorize with Librarian

Consult the project's librarian agent (if exists) or categorize:

Questions to determine category:
- Is this "how we do X"? → `patterns/`
- Is this "why we chose X"? → `decisions/`
- Is this "watch out for X"? → `gotchas/`
- Is this "to do X, follow these steps"? → `how-to/`
- Is this "how X works in our system"? → `architecture/`
- Is this "to debug X, check Y"? → `debugging/`
- Is this "we name things X way"? → `conventions/`
- Is this "X external system works like Y"? → `integrations/`

### Phase 3: Check for Duplicates

```bash
# Search existing knowledge base
grep -ri "[key terms]" ai-lookup/

# Check if this updates existing entry
ls ai-lookup/[category]/
```

If duplicate:
- Update existing entry (add new information)
- Note the update date
- Don't create new file

### Phase 4: Compress and Clean

Transform conversation knowledge into library entry:

**From conversation:**
> "So I was debugging this for 3 hours and finally figured out that when you use context.WithTimeout, you MUST call the cancel function or you leak resources. This bit me because I forgot the defer cancel()..."

**Compressed to:**
```markdown
# context.WithTimeout Requires defer cancel()

## Summary
`context.WithTimeout` returns a cancel function that MUST be called (typically with `defer`) or resources will leak. The cancel function releases resources associated with the context.

## Details
The WithTimeout function signature returns both a context and a cancel function:
- Always capture and call the cancel function
- Use defer immediately after creating the context
- Failure to cancel leaks goroutines and memory

## Example
```go
// BAD - leaks resources
ctx, _ := context.WithTimeout(parentCtx, 5*time.Second)

// GOOD - always defer cancel
ctx, cancel := context.WithTimeout(parentCtx, 5*time.Second)
defer cancel()
```
```

### Phase 5: Write Entry

Create the file in appropriate location:

```bash
mkdir -p ai-lookup/[category]
```

Write with full format (frontmatter + content).

### Phase 6: Update Indexes

Update `ai-lookup/[category]/index.md`:
```diff
+ - [Entry Title](entry-name.md) - Brief description
```

Update `ai-lookup/index.md` if new category:
```diff
+ ## [Category]
+ - [Entry](category/entry.md) - Description
```

### Phase 7: Verify Discoverability

Can this be found by:
1. Browsing the index?
2. Searching for key terms?
3. Following related links?

## Compression Guidelines

| Verbose | Compressed |
|---------|-----------|
| Long explanation of discovery process | Just the fact |
| "I think maybe..." hedging | Direct statement with confidence rating |
| Multiple examples | One clear example |
| Conversation back-and-forth | Clean Q&A or just answer |
| Implementation details that change | Concept that's stable |

## What to Remember vs Not

**Remember:**
- Non-obvious behaviors (gotchas)
- Decisions and their rationale
- Patterns that recur
- Debugging strategies that worked
- Integration quirks
- Performance insights

**Don't Remember:**
- Obvious/documented facts (link to docs instead)
- Temporary workarounds (track as tech debt)
- One-off fixes (just fix it)
- Personal preferences (unless team convention)
- Speculation (wait until confirmed)

## Freshness Management

Add `last_verified` to entries that might become stale:

```yaml
---
learned: 2024-01-15
last_verified: 2024-06-20
stale_after: 2025-01-15  # optional
---
```

When reading old entries, check if still accurate.

## Do

1. Compress to essence (not conversation transcript)
2. Categorize thoughtfully (enables discovery)
3. Include concrete examples
4. Link to related entries
5. Track provenance (when, how learned)
6. Update existing entries (don't duplicate)
7. Verify discoverability

## Do Not

1. Store conversation verbatim (compress!)
2. Duplicate existing knowledge (update instead)
3. Store temporary information (use todo/tickets)
4. Forget provenance (when/how learned)
5. Skip indexes (discovery depends on it)
6. Store speculation as fact (note confidence)

## Constraints

- ALWAYS include frontmatter with category, learned date, confidence
- ALWAYS update indexes when adding entries
- ALWAYS compress conversation to essence
- NEVER duplicate existing entries (update them)
- NEVER store without checking for existing knowledge
- ALWAYS include at least one example for patterns/gotchas

## Output Format

```markdown
## Remembered: [Title]

### Classification
- **Category:** [category]
- **Confidence:** [high/medium/low]
- **Source:** [how learned]

### Stored At
`ai-lookup/[category]/[filename].md`

### Entry Preview
[First few lines of the created entry]

### Indexes Updated
- `ai-lookup/index.md` - [added/updated]
- `ai-lookup/[category]/index.md` - [added/updated]

### Related Entries
- [Existing related knowledge]

### Verification
- [ ] Searchable by key terms
- [ ] Indexed in category
- [ ] Linked to related entries
```