compound-retrieve

Compound Retrieve

Goal

Surface institutional knowledge from past solutions and engineering principles before starting work. Prevent repeated mistakes by searching YAML-frontmatter solution files captured by compound-capture.

Dependencies

Tools

• compound-knowledge:knowledge-researcher — Haiku-powered subagent that performs fast, parallel grep-based retrieval across solution files. Designed for speed (<30s).

Connectors

• Solutions directory — Resolved via path resolution (see Context). Default: {project_root}/knowledge/solutions/
• Cross-project registry — ~/.claude/compound-knowledge-registry.md. Enables searching other projects' knowledge bases when local results are thin.

Context

Path Resolution

Resolve the solutions directory before any operation. First match wins:

1. Project-level override: Read {project_root}/.claude/compound-knowledge.local.md — extract solutions_path value
2. User-level override: Read ~/.claude/compound-knowledge.local.md — extract solutions_path value
3. Default: {project_root}/knowledge/solutions/

If the resolved directory does not exist:

"Solutions directory not found at {solutions_path}. Run /compound-knowledge:setup to initialize it."

When to Retrieve

• Before non-trivial debugging: "Let me check if we've seen this before..."
• During planning phases: "Checking for relevant past solutions..."
• When encountering errors: Search by symptom/error message
• When working on a project: Search by project name for all related solutions
• Making design decisions: Surface relevant principles and past architectural choices
• Working in unfamiliar code: Check for documented patterns and gotchas

Process

Step 0: Load Stored Feedback

Load any stored feedback preferences before starting:

python ${PLUGIN_ROOT}/scripts/feedback_manager.py compound-knowledge show-feedback

If feedback entries exist, apply them:

• retrieval_depth → adjust how many results are surfaced
• general → apply to result formatting and presentation

Step 1: Resolve Solutions Path

Follow the Path Resolution algorithm from Context. Store as {solutions_path}.

Step 2: Delegate to Knowledge Researcher

Spawn the subagent for fast parallel search:

Agent(
  subagent_type="compound-knowledge:knowledge-researcher",
  model="haiku",
  prompt="Search for solutions related to: {task_description}. Project: {project_name}. Keywords: {extracted_keywords}. Solutions path: {solutions_path}. Registry path: ~/.claude/compound-knowledge-registry.md",
  description="Search past solutions"
)

The researcher reads the registry to identify other knowledge bases for cross-project search when primary results are thin (<3 hits).

Step 3: Interpret and Apply Results

The knowledge-researcher returns:

1. Critical patterns — always-relevant warnings from critical-patterns.md
2. Relevant principles — engineering wisdom that applies to the current task
3. Ranked solutions — scored by project, component, symptom, and tag relevance
4. Cross-project results — solutions from other registered knowledge bases
5. Recommendations — actionable suggestions based on found solutions

Surface the top results to the user and incorporate insights into your approach:

• If a critical pattern matches → warn the user prominently
• If a principle applies → reference it when making design decisions
• If a past solution matches → suggest the documented fix
• If nothing found → say so clearly, don't fabricate relevance

Output

A concise summary of relevant past solutions and principles, presented to the user with:

• File paths for deeper reading
• Actionable recommendations based on findings
• Prominent warnings for any matching critical patterns