Compound Knowledge Capture Protocol

Principle: First-time problem solving (30 min) becomes future lookup (minutes).

When to Trigger

Automatic Detection (in /session-end)

Prompt "Document what you learned?" when ANY of these apply:

1. •

   Bug fix commits detected

   • •Commit messages contain: "fix", "bug", "resolve", "patch", "hotfix"
   • •Multiple commits touching the same file
2. •

   Significant investigation work

   • •Session lasted 30+ minutes on a single issue
   • •Multiple approaches tried before success
   • •Error messages encountered and resolved
3. •

   New pattern introduced

   • •First usage of a library/API in the project
   • •Architectural decision made and implemented
   • •Workaround for a limitation discovered
4. •

   User explicitly requests

   • •User says "let's document this"
   • •User runs /compound directly

Capture Process

Step 1: Analyze Session

Review to identify:

Sources to examine:
- Recent commits (git log --oneline -10)
- PROGRESS.md last entry
- Conversation history in this session
- Modified files (git diff --stat)

Extract:

• •What was the problem?
• •What was tried?
• •What worked?

Step 2: Extract Problem

Identify and document:

## Symptoms
- [Error message 1]
- [Unexpected behavior]
- [When/where it occurred]

Look for:

• •Stack traces
• •Error messages
• •Unexpected behavior descriptions

Step 3: Extract Investigation

Document the journey:

## Investigation

### What I tried
1. [First attempt] — Result: [didn't work because...]
2. [Second attempt] — Result: [partially worked]
3. [Final approach] — Result: [success]

### Root Cause
[The actual underlying issue]

Include failures — they're valuable for future searchers.

Step 4: Extract Solution

Capture the working fix:

## Solution

\`\`\`[language]
// Working code
\`\`\`

**Steps:**
1. [Step 1]
2. [Step 2]

Step 5: Categorize

Determine the best category:

Step 6: Scope Decision

Ask or determine:

Project-local (solutions/):

• •Specific to this codebase
• •Uses project conventions
• •References project files

Global (~/.claude/solutions/[tech]/):

• •Applies to any project with this tech
• •General framework pattern
• •Would help in other codebases

Step 7: Generate Document

Create solution document with:

# [Brief Problem Description]

> **Category:** [category]
> **Created:** [YYYY-MM-DD]
> **Project:** [project-name or "universal"]
> **Keywords:** [searchable, comma, separated]

## Symptoms
[From Step 2]

## Investigation
[From Step 3]

## Solution
[From Step 4]

## Prevention
- [ ] Add test case
- [ ] Update CLAUDE.md
- [ ] Create lint rule (if applicable)

## Related
- [Links to docs, issues, etc.]

Step 8: Write File

Save to appropriate location:

# Project-local
solutions/[category]/[slug].md

# Global
~/.claude/solutions/[tech]/[slug].md

Filename format: [topic]-[specific-issue].md

• •Use lowercase
• •Use hyphens for spaces
• •Keep descriptive but concise

Example Flow

Session: Fixed TypeScript path alias issue that broke imports

Step 1: Analyze
- Commits: "fix: resolve path alias in tsconfig"
- Modified: tsconfig.json, vite.config.ts

Step 2: Extract Problem
- Error: "Cannot find module '@/components/Button'"
- Symptom: Imports worked in IDE but failed at build

Step 3: Extract Investigation
- Tried: Adding paths to tsconfig (didn't fix build)
- Tried: vite-tsconfig-paths plugin (worked!)
- Root cause: Vite doesn't read tsconfig paths by default

Step 4: Extract Solution
- Install vite-tsconfig-paths
- Add to vite.config.ts plugins

Step 5: Categorize
- Category: build-errors

Step 6: Scope
- Global (applies to any Vite + TypeScript project)

Step 7: Generate
- Create document with all sections

Step 8: Write
- Save to: ~/.claude/solutions/typescript/vite-path-aliases.md

Integration Points

With /session-end

After verification steps, check for compound triggers:

/session-end
    |-- Verify code state
    |-- Archive old sessions
    |-- Update PROGRESS.md
    |-- [Check compound triggers]
    |   +-- If triggered -> "Document what you learned? (y/n)"
    |       +-- If yes -> Run compound capture
    +-- Create commit

With /session-start

Search solutions library before beginning work:

/session-start
    |-- Check environment
    |-- [Search solutions for current task keywords]
    |   +-- If matches found -> "Relevant prior solutions: [list]"
    |-- Read recent progress
    +-- Find current task

AskUserQuestion Integration

When running interactively, use AskUserQuestion:

Q1: "Capture this learning?"

• •A) Yes, save to project solutions
• •B) Yes, save to global solutions
• •C) No, skip

Q2 (if yes): "Which category?"

• •A) Build error
• •B) Test failure
• •C) Runtime error
• •D) Other (specify)

Quality Checklist

Before saving, verify:

• • Searchable: Keywords would help someone find this
• • Reproducible: Solution steps are complete
• • Portable: Could be understood without full context
• • Actionable: Reader knows exactly what to do

Protocol version: 1.0 | Created: 2026-02-01