knowledge-extractor

What this skill does

# Knowledge Extractor Skill

## Purpose

This skill automatically extracts, synthesizes, and preserves knowledge from conversations, debugging sessions, failed attempts, and solved problems. It converts ephemeral interactions into persistent organizational knowledge that improves future performance.

## When to Use This Skill

- **Session End Analysis**: Extract learnings before session context is lost
- **After Complex Debugging**: Capture root causes and solutions while fresh
- **Following Failed Attempts**: Document what didn't work and why
- **Successful Problem Solving**: Preserve solutions for future reuse
- **New Pattern Discovery**: Identify patterns that should be documented
- **Repeated Workflows**: Recognize when to create new specialized agents
- **Cross-Session Learning**: Build organizational memory from individual sessions

## Core Philosophy: Knowledge Preservation

**Session Context**: Ephemeral conversation context that will be lost without active preservation
**Persistent Knowledge**: Structured learnings that improve future performance
**Pattern Recognition**: Identifying when solutions are repeated and should be automated
**Organizational Growth**: Converting individual learning into system-wide improvement

## Knowledge Extraction Framework

### Three Types of Knowledge Extraction

#### 1. Discoveries - Novel Insights and Root Causes

**What it captures**: Problems encountered, root causes identified, solutions implemented

**When to extract**:

- After solving a complex bug
- When debugging reveals unexpected behavior
- When discovering wrong assumptions
- After identifying missing functionality
- When learning why something failed

**Format for DISCOVERIES.md**:

```markdown
## [Brief Title] (YYYY-MM-DD)

### Issue

What problem or challenge was encountered?

### Root Cause

Why did this happen? What was the underlying issue?

### Solution

How was it resolved? Include code examples if relevant.

### Key Learnings

What insights were gained? What should be remembered?

### Prevention

How can this be avoided in the future?
```

**Quality Criteria**:

- ✅ Specific problem, not generic advice
- ✅ Root cause clearly identified
- ✅ Working solution included
- ✅ Learning generalized for reuse
- ✅ Prevention strategy documented

#### 2. Patterns - Reusable Solutions

**What it captures**: Proven solutions to recurring problems, architectural approaches, design patterns

**When to extract**:

- After solving a problem similar to known patterns
- When recognizing a repeated problem type
- When implementing a proven solution
- When discovering a best practice that works
- When solution applies across multiple contexts

**Format for PATTERNS.md**:

```markdown
## Pattern: [Name]

### Challenge

What problem does this pattern solve?

### Solution

How does the pattern work? Include code/examples.

### Key Points

- Main insight 1
- Main insight 2
- When to use / when not to use

### When to Use

Specific scenarios where this pattern applies.

### Real Impact

Where has this pattern been used successfully?

### Related Patterns

Links to similar or complementary patterns.
```

**Quality Criteria**:

- ✅ General enough to apply to multiple situations
- ✅ Problem clearly defined
- ✅ Solution has proven track record
- ✅ Working code examples
- ✅ Clear when/when-not-to-use guidance

#### 3. Agent Creation - Automation of Repeated Workflows

**What it captures**: Workflows that are repeated frequently, specialized expertise areas, complex multi-step processes

**When to extract**:

- After performing the same workflow 2-3 times
- When recognizing a specialized skill area
- When workflow has clear inputs/outputs
- When automating would save significant time
- When problem domain is narrow and well-defined

**Agent Creation Trigger Checklist**:

- [ ] Same workflow repeated 2+ times
- [ ] Workflow takes 30+ minutes to execute
- [ ] Workflow has clear specialized focus
- [ ] Workflow can be automated with current tools
- [ ] Problem domain is narrow and well-defined
- [ ] Would be high-value to automate

**Example Agent Creation**:

```markdown
## Recommended New Agent: [domain]-[specialty]

### Problem

What repeated workflow would this agent handle?

### Scope

What's in scope | What's explicitly out of scope

### Inputs

What information does the agent need?

### Process

Step-by-step workflow the agent follows

### Outputs

What does the agent produce?

### Value

How much time/effort does this save?

### Integration

Where in the workflow does this fit?
```

## Step-by-Step Extraction Process

### Step 1: Session Analysis (5 minutes)

Review entire conversation/session:

```
1. What was the original problem/request?
2. What approaches were tried?
3. Which attempts failed and why?
4. What succeeded and why?
5. What was learned in the process?
6. What surprised you?
7. What took longer than expected?
8. What would have helped?
```

### Step 2: Pattern Recognition (5 minutes)

Identify patterns in the work:

```
1. Have I seen this problem before? (→ DISCOVERIES)
2. Is this a generalizable solution? (→ PATTERNS)
3. Would this be worth automating? (→ AGENT)
4. What was the root cause? (Why, not just what)
5. What should others know about this?
6. What should be remembered to avoid repetition?
```

### Step 3: Knowledge Extraction (10 minutes)

Extract and structure knowledge:

**For DISCOVERIES.md**:

- Specific issue encountered
- Root cause analysis
- Solution implemented
- Key learnings generalized
- Prevention strategy

**For PATTERNS.md**:

- Problem the pattern solves
- How the pattern works
- When to use / when not to use
- Working code examples
- Related patterns

**For New Agent**:

- Repeated workflow identified
- Clear scope and boundaries
- Input/output requirements
- Step-by-step process
- Expected value/time savings

### Step 4: Integration (3 minutes)

Place knowledge in correct locations:

```
Memory → Store discovery using store_discovery() from amplihack.memory.discoveries
PATTERNS.md → New pattern in appropriate section
Agent → Create in .claude/agents/amplihack/specialized/
```

### Step 5: Validation (2 minutes)

Ensure quality:

```
[ ] Entry is specific, not generic
[ ] Entry follows template format
[ ] Examples/code provided
[ ] Quality sufficient for reuse
[ ] Grammar and clarity checked
[ ] Related items cross-referenced
```

## Usage Examples

### Example 1: Extract Discovery After Bug Fix

**Scenario**: Just spent 45 minutes debugging why pre-commit hooks weren't working

```
User: Extract what we learned from debugging the pre-commit issue.

Claude:
1. Analyzes conversation showing:
   - Initial problem: hooks appeared to run but didn't modify files
   - False leads: blamed merge conflicts, tool versions
   - Root cause found: Hooks couldn't write to files due to cloud sync lock
   - Solution: Added exponential backoff retry logic
   - Time to discover: 45 minutes

2. Creates DISCOVERIES.md entry:
   - Issue: Pre-commit hooks silently failing
   - Root Cause: Cloud sync (OneDrive) file locks
   - Solution: Exponential backoff retry (0.1s, 0.2s, 0.4s...)
   - Key Learning: Cloud sync issues silent - need defensive coding
   - Prevention: Add retry logic for file I/O, test with cloud storage

3. Offers to also:
   - Add pattern for "Resilient File I/O" to PATTERNS.md
   - Suggest new agent for cloud-sync issue detection
```

### Example 2: Extract Pattern from Successful Implementation

**Scenario**: Just finished implementing module regeneration strategy

```
User: Extract the pattern we discovered for building regeneratable modules.

Claude:
1. Analyzes implementation showing:
   - Clear __all__ exports defining public interface
   - Self-contained module structure
   - Type-hinted functions with docstrings
   - Comprehensive test coverage
   - Working examples

2. Creates PATTERNS.md entry:
   - Pattern: Module Regeneration Structure
   - Challenge: Modules become tightly coupled, hard to regenerate
   - Solution