# Compound > Capture session learnings as searchable solution documents Use when this capability is needed. - Skill: `tomevault-io/compound` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/compound` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/compound/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/compound --- # 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: ```markdown ## 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: ```markdown ## 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: ```markdown ## Solution \`\`\`[language] // Working code \`\`\` **Steps:** 1. [Step 1] 2. [Step 2] ``` ### Step 5: Categorize Determine the best category: | Category | Use When | |----------|----------| | `build-errors/` | TypeScript, compilation, bundler issues | | `test-failures/` | Test suite problems | | `runtime-errors/` | Runtime exceptions, crashes | | `performance-issues/` | Speed, memory optimizations | | `integration-issues/` | API, database, external services | | `patterns/` | Reusable architectural patterns | ### 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: ```markdown # [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: ```bash # 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* --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/matthewod11-stack) — claim your Tome and manage your conversions.