compound-capture

Compound Capture

Goal

Capture solved problems and engineering principles as searchable YAML-frontmatter markdown files. Every capture creates a structured file that enables fast grep-based retrieval in future sessions, across projects.

Dependencies

Tools

• Grep — Searches existing solutions for duplicates and cross-references
• Glob — Counts solution files for registry updates
• Write/Edit — Creates solution files and updates cross-references

Connectors

• Solutions directory — write_path from scripts/resolve_paths.py (see Context)
• Cross-project registry — ~/.claude/compound-knowledge-registry.md. Tracks all knowledge bases on the machine.

Context

Path Resolution

Resolve the solutions directory before any operation by running the resolver on the project root:

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/resolve_paths.py" "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"

It prints JSON; captures go to its write_path, stored as {write_path}. Never read the config file yourself.

If the resolver exits 1, it still printed its JSON and write_path does not exist. Stop and tell the user what it printed to stderr (create the directory with mkdir -p {write_path}, or run /compound-knowledge:setup if there is no config yet). Any other failure prints no JSON: report the error and stop rather than guessing a path.

Triviality Filter

Skip capture for: typos, syntax errors, missing imports, one-line fixes with no investigation, obvious bugs caught immediately.

Proceed with capture for: problems requiring multiple investigation attempts, non-obvious root causes, solutions involving code examples or architecture decisions, issues likely to recur.

Solution vs Principle

Directory Structure

{write_path}/
├── debugging/        # Service failures, error diagnosis
├── infrastructure/   # Networking, storage, resource issues
├── patterns/         # Design patterns, architectural approaches
├── workflow/         # Process improvements, scope management
├── performance/      # Speed, resource optimization
├── security/         # Vulnerability fixes, secrets management
├── ci-cd/           # Pipeline issues, publishing, deployment
├── configuration/    # Config management, env vars, settings
├── migration/        # System transitions, format changes
├── integration/      # Cross-system compatibility
├── principles/       # Engineering wisdom and governing principles
└── critical-patterns.md  # High-severity patterns (always read)

YAML Schema and Templates

For field definitions, enum values, and validation rules:

→ references/yaml-schema.md

For file templates:

→ references/solution-template.md → references/principle-template.md

For cross-project registry schema:

→ references/registry-format.md

Process

Step 1: Resolve Solutions Path

Run the resolver as described in Path Resolution and store its write_path as {write_path}.

Step 2: Apply Triviality Filter

If the problem is trivial (see filter in Context), skip capture.

If unsure:

"This seems like a solution worth documenting. Want me to capture it?"

Step 3: Gather Context

Determine whether this is a solution or a principle (see Context table).

For solutions, extract from the conversation:

For principles, extract:

If critical fields are missing, ask and wait:

"I need a few details to capture this properly: What project is this for? What were the symptoms?"

Step 4: Check for Duplicates

Search {write_path} for similar existing solutions:

Grep(pattern="symptoms:.*{key_symptom}", path="{write_path}", output_mode="files_with_matches")
Grep(pattern="title:.*{similar_term}", path="{write_path}", output_mode="files_with_matches")

Ignore hits under _archive/: those lessons were retired, so never update or link to them.

• Different root cause → Create new file, add related_solutions cross-reference
• Same issue, new context → Update existing file
• Exact duplicate → Skip, inform user: "This is already documented in [file]"

Step 5: Validate YAML

Read references/yaml-schema.md and validate all enum fields. Block creation if validation fails. Report which fields are invalid and suggest corrections.

Human Checkpoint: Present Capture Summary

Before writing, present:

Capturing: {solution|principle}
  Title: {title}
  Project: {project}
  Component: {component}
  Category: {problem_type} → {write_path}/{category}/
  Severity: {severity}
  File: {filename}.md

Proceed?

Wait for user confirmation before writing.

Step 6: Create File

1. Generate filename: {sanitized-symptom}-{project}-{YYYYMMDD}.md (lowercase, hyphens, max 80 chars)
2. Read the appropriate template: references/solution-template.md or references/principle-template.md
3. Write the file with validated YAML frontmatter and structured content

Step 7: Cross-Reference with Bidirectional Links

Links must be bidirectional — if file A references file B, file B must reference file A.

1. Add related_solutions entries to the new file pointing to matches from Step 4
2. Update each related file to add a backlink (cap at 5 entries per file)
3. Use category/filename.md format for all paths (never absolute paths)

Present summary:

Created: {write_path}/{category}/{filename}.md
Related solutions:
  - [title](path) — {why related}
Updated backlinks in:
  - {path1}
  - {path2}

Step 8: Update Registry

Update ~/.claude/compound-knowledge-registry.md so this knowledge base is discoverable from other projects.

1. Read the registry (create from references/registry-format.md header if missing)
2. Count solution files and extract unique components
3. Update existing entry in-place (path is unique key) or append new entry

Output

A structured markdown file in {write_path}/{category}/ with: - YAML frontmatter validated against references/yaml-schema.md - Structured body following references/solution-template.md or references/principle-template.md - Bidirectional cross-references to related solutions - Updated cross-project registry entry