Internal Module: Called by /reflect for knowledge capture.
Use /reflect directly, or /reflect --knowledge for knowledge-only capture.
Compound-Docs — Knowledge Note Generator
Purpose
Generate structured learning documents from solved problems. This module handles:
- Context gathering (problem, root cause, solution, files, tags)
- Category auto-detection
- Learning document generation (YAML frontmatter + markdown)
- Entity sidecar generation for GraphRAG indexing
- Saving to
docs/solutions/ and promoting to global KB
Context to Gather
- Problem: Error message, observed vs expected behavior
- Root Cause: What actually caused it, why
- Solution: What fixed it, key insight, steps
- Files: Which files were modified or had the bug
- Tags: Technologies involved, searchable keywords
Category Auto-Detection
| Category |
Indicators |
build-errors |
Compile errors, CI failures, bundling |
performance-issues |
Slowdowns, memory leaks, optimization |
security-fixes |
Vulnerabilities, auth issues, secrets |
testing-patterns |
Test strategies, flaky tests |
debugging-sessions |
Complex investigations |
architecture-decisions |
Design choices, patterns |
api-integrations |
Third-party APIs, SDKs |
dependency-issues |
Package conflicts, upgrades |
deployment-fixes |
Production incidents |
database-migrations |
Schema changes, data fixes |
ui-patterns |
Frontend patterns, CSS |
tooling-setup |
Dev environment, configs |
Learning Document Format
---
title: "[Brief descriptive title]"
category: [auto-detected or specified]
tags: [extracted tags]
symptoms:
- "[Error message or behavior]"
root_cause: "[What actually caused it]"
key_insight: "[THE ONE THING that fixes it]"
created: [today's date]
confidence: [high|medium|low]
language: [if applicable]
framework: [if applicable]
---
## Problem
[Description]
## Solution
[Steps with code examples]
## Context
[Why it happened, how to prevent]
Entity Extraction
For GraphRAG indexing, extract entities and relationships.
See reflect/references/knowledge_format.md for entity types,
relationship types, extraction guidelines, and sidecar format.
Saving
# Project-local
mkdir -p docs/solutions/[category]
# Save: docs/solutions/[category]/[filename].md
# Global promotion (via CLI)
LEARNINGS_CLI="$LEARNINGS_HOME/cli/learnings"
if [[ -x "$LEARNINGS_CLI" ]]; then
"$LEARNINGS_CLI" add docs/solutions/[category]/[filename].md \
--entities docs/solutions/[category]/[filename].entities.yaml
fi
Quality Checklist
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: stevengonsalvez-agents-in-a-box-compound-docs3description: > **Internal Module**: Called by `/reflect` for knowledge capture.4---56> **Internal Module**: Called by `/reflect` for knowledge capture.7> Use `/reflect` directly, or `/reflect --knowledge` for knowledge-only capture.89# Compound-Docs — Knowledge Note Generator1011## Purpose1213Generate structured learning documents from solved problems. This module handles:141. Context gathering (problem, root cause, solution, files, tags)152. Category auto-detection163. Learning document generation (YAML frontmatter + markdown)174. Entity sidecar generation for GraphRAG indexing185. Saving to `docs/solutions/` and promoting to global KB1920## Context to Gather21221. **Problem**: Error message, observed vs expected behavior232. **Root Cause**: What actually caused it, why243. **Solution**: What fixed it, key insight, steps254. **Files**: Which files were modified or had the bug265. **Tags**: Technologies involved, searchable keywords2728## Category Auto-Detection2930| Category | Indicators |31|----------|------------|32| `build-errors` | Compile errors, CI failures, bundling |33| `performance-issues` | Slowdowns, memory leaks, optimization |34| `security-fixes` | Vulnerabilities, auth issues, secrets |35| `testing-patterns` | Test strategies, flaky tests |36| `debugging-sessions` | Complex investigations |37| `architecture-decisions` | Design choices, patterns |38| `api-integrations` | Third-party APIs, SDKs |39| `dependency-issues` | Package conflicts, upgrades |40| `deployment-fixes` | Production incidents |41| `database-migrations` | Schema changes, data fixes |42| `ui-patterns` | Frontend patterns, CSS |43| `tooling-setup` | Dev environment, configs |4445## Learning Document Format4647```yaml48---49title: "[Brief descriptive title]"50category: [auto-detected or specified]51tags: [extracted tags]52symptoms:53 - "[Error message or behavior]"54root_cause: "[What actually caused it]"55key_insight: "[THE ONE THING that fixes it]"56created: [today's date]57confidence: [high|medium|low]58language: [if applicable]59framework: [if applicable]60---6162## Problem63[Description]6465## Solution66[Steps with code examples]6768## Context69[Why it happened, how to prevent]70```7172## Entity Extraction7374For GraphRAG indexing, extract entities and relationships.75See `reflect/references/knowledge_format.md` for entity types,76relationship types, extraction guidelines, and sidecar format.7778## Saving7980```bash81# Project-local82mkdir -p docs/solutions/[category]83# Save: docs/solutions/[category]/[filename].md8485# Global promotion (via CLI)86LEARNINGS_CLI="$LEARNINGS_HOME/cli/learnings"87if [[ -x "$LEARNINGS_CLI" ]]; then88 "$LEARNINGS_CLI" add docs/solutions/[category]/[filename].md \89 --entities docs/solutions/[category]/[filename].entities.yaml90fi91```9293## Quality Checklist9495- [ ] Title is descriptive (searchable)96- [ ] Key insight is THE ONE THING (not a summary)97- [ ] Symptoms include actual error messages98- [ ] Tags cover relevant technologies99- [ ] Category is correct100- [ ] Confidence reflects certainty101102---103> Converted and distributed by [TomeVault](https://tomevault.io/claim/stevengonsalvez) — claim your Tome and manage your conversions.104<!-- tomevault:4.0:skill_md:2026-04-11 -->