feat-dev-e2e3/.claude/commands/remember.md

---
description: Store learnings as discoverable institutional memory, organized by the librarian
argument-hint: <what to remember, or "from discussion" to extract from conversation>
allowed-tools: Task, Read, Write, Edit, Glob, Grep, Bash
---

Remember this knowledge: $ARGUMENTS

## Instructions

Load the `knowledge-librarian` skill, then:

### 1. Extract the Learning

If "from discussion":
- Review the conversation
- Identify key insights, decisions, gotchas, patterns learned
- May extract multiple memories

If specific topic:
- Clarify what exactly to remember
- Identify the core insight

```markdown
**What:** [The knowledge]
**Why it matters:** [When someone would need this]
**Confidence:** [high/medium/low]
**Source:** [conversation/investigation/incident]
```

### 2. Consult Librarian Agent

If project has `.claude/agents/librarian.md`:
```
Launch librarian agent to:
1. Categorize this knowledge
2. Check for existing related entries
3. Suggest where to store it
4. Identify connections to existing knowledge
```

Otherwise, self-categorize:

| If it's... | Category |
|------------|----------|
| "How we do X" | `patterns/` |
| "Why we chose X" | `decisions/` |
| "Watch out for X" | `gotchas/` |
| "Steps to do X" | `how-to/` |
| "How X works" | `architecture/` |
| "To debug X" | `debugging/` |
| "We name X like Y" | `conventions/` |
| "External X works like Y" | `integrations/` |

### 3. Check for Duplicates

```bash
# Search existing knowledge
grep -ri "[key terms]" ai-lookup/ 2>/dev/null

# List category
ls ai-lookup/[category]/ 2>/dev/null
```

If exists: UPDATE don't duplicate.

### 4. Compress the Knowledge

Transform verbose conversation into compressed entry:

**From:** Long explanation with context, discovery process, tangents...
**To:** Core fact + one example + links

Keep:
- The essential insight
- One clear example
- Related links

Remove:
- Discovery narrative
- Hedging language
- Redundant examples
- Temporary context

### 5. Write the Entry

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

Format:
```markdown
---
category: [category]
title: [Searchable title]
learned: [YYYY-MM-DD]
source: [conversation|investigation|incident]
confidence: [high|medium|low]
related: []
---

# [Title]

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

## Details
[Compressed knowledge]

## Example
[Concrete example]

## See Also
- [Related](path/to/related.md)
```

### 6. Update Indexes

**Category index** (`ai-lookup/[category]/index.md`):
```diff
+ - [Title](filename.md) - Brief description
```

**Master index** (`ai-lookup/index.md`):
```diff
+ - [Title](category/filename.md) - Brief description
```

Create indexes if they don't exist.

### 7. Verify Discoverability

- [ ] Can find by browsing index
- [ ] Can find by grep for key terms
- [ ] Links to related entries work

## Entry Templates

### Pattern
```markdown
---
category: patterns
title: [Pattern Name]
learned: YYYY-MM-DD
confidence: high
---

# [Pattern Name]

## Summary
[When to use this pattern and why]

## Pattern
[The pattern itself]

## Example
```code
[Concrete example]
```

## When NOT to Use
[Exceptions or anti-patterns]
```

### Gotcha
```markdown
---
category: gotchas
title: [Short description of trap]
learned: YYYY-MM-DD
confidence: high
---

# [Gotcha Title]

## Summary
[One sentence: what bites you]

## The Problem
[What goes wrong]

## The Solution
[How to avoid/fix]

## Example
```code
// BAD
[code that breaks]

// GOOD
[code that works]
```
```

### Decision
```markdown
---
category: decisions
title: [Decision: X over Y]
learned: YYYY-MM-DD
confidence: high
---

# [Decision Title]

## Summary
We chose [X] over [Y] because [reason].

## Context
[What prompted this decision]

## Options Considered
1. **[X]** - [pros/cons]
2. **[Y]** - [pros/cons]

## Decision
[What we chose and why]

## Consequences
[What this means going forward]
```

### How-To
```markdown
---
category: how-to
title: How to [do X]
learned: YYYY-MM-DD
confidence: high
---

# How to [Do X]

## Summary
[When you'd need this]

## Prerequisites
- [What you need first]

## Steps
1. [Step 1]
2. [Step 2]
3. [Step 3]

## Verification
[How to know it worked]

## Troubleshooting
- **[Problem]**: [Solution]
```

## Output Format

```markdown
## Remembered: [Title]

**Category:** [category]
**Confidence:** [level]
**Stored:** `ai-lookup/[category]/[filename].md`

### Entry Created

```markdown
[Preview of created entry]
```

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

### Related Knowledge
- [Existing related entries found]

### Discoverability Check
- [x] Indexed
- [x] Searchable by: [key terms]
- [x] Linked to related
```

## Quick Examples

**Remember a gotcha:**
```
/remember "context.WithTimeout requires defer cancel() or resources leak"
→ ai-lookup/gotchas/context-cancel-required.md
```

**Remember a decision:**
```
/remember "We chose slog over logrus because structured logging with stdlib"
→ ai-lookup/decisions/slog-over-logrus.md
```

**Remember from discussion:**
```
/remember from discussion
→ Extracts key learnings from conversation
→ Creates appropriate entries
```

## Critical Rules

- COMPRESS: Essence not transcript
- CATEGORIZE: Enables discovery
- CHECK: Don't duplicate
- INDEX: Update both indexes
- VERIFY: Ensure findable
- PROVENANCE: Track when/how learned