# Compound Learning ↔ Hindsight Bridge

Architecture for connecting file-based knowledge (`docs/solutions/`) with semantic search (Hindsight PostgreSQL). Enables solutions to be found by meaning, not just by keyword.

## Problem

`docs/solutions/` files are only discoverable via `search_files` (keyword/regex). A solution titled "Sequential SST Recovery" is invisible to a search for "Galera bootstrap failure" — different words, same problem. Hindsight's vector embeddings solve this, but solutions weren't indexed there.

## Solution: Three Bridges

### Bridge A — Write-Side (compound-learning → Hindsight)

Location: `compound-learning` SKILL.md, Phase 4.5

After writing a solution doc to `docs/solutions/{type}/{date}-{slug}.md`, sync a compact summary to Hindsight:

```python
hindsight_retain(
    content=f"SOLUTION [{problem_type}]: {problem_summary}. "
            f"Root cause: {root_cause}. Fix: {fix}. "
            f"Lesson: {lesson}. Tags: {tags}. "
            f"Source: docs/solutions/{type}/{date}-{slug}.md",
    context="compound-learning solution doc",
    tags=["solution"] + tags
)
```

**Content policy:** File = full detail (context, code, prevention). Hindsight = compact summary + tags + source path. Never duplicate the full doc into Hindsight.

**Graceful degradation:** If Hindsight daemon is down (`curl -s http://127.0.0.1:9177/health` fails), skip the sync. The file in `docs/solutions/` is always sufficient on its own.

### Bridge B — Read-Side (Grounding Scans → Hindsight)

Locations: `brainstorming` Step 1.5, `plan` Step 1.5, `writing-plans` Step 1.5

Grounding Scans now query BOTH sources:

1. `search_files("keyword", path="docs/solutions/")` — keyword match, returns full file paths
2. `hindsight_recall("topic description")` — semantic match, catches solutions with different keywords

Merge results: file hits give full detail, Hindsight hits give semantic matches + cross-project patterns.

### Bridge C — Auto-Surfacing (Weekly Digest → Solutions)

Location: `scripts/hindsight_weekly_digest.py`, section 5

The weekly digest now includes a "Solution Patterns (Compound Learning)" section that:
- Queries Hindsight for SOLUTION-prefixed entries
- Identifies recurring problem types
- Surfaces lessons relevant for future planning

Budget: `mid`. Silent when no solutions stored.

## Data Flow

```
Problem solved
    ↓
compound-learning Phase 1-4: Solution file in docs/solutions/
    ↓
Phase 4.5: hindsight_retain(summary + tags + source path)
    ↓
Hindsight PostgreSQL (semantic index)
    ↓
Next plan/brainstorm:
  Grounding Scan → search_files (keyword) + hindsight_recall (semantic)
    ↓
Weekly: Digest → Solution Patterns → Recommendations
```

## Three-Tier Memory Strategy

| Layer | Scope | Capacity | Retrieval |
|---|---|---|---|
| MEMORY.md | Hot facts, TODOs, quick refs | ~2,200 chars | Injected every turn |
| Hindsight | Unlimited detail, history, context | Unbounded (PostgreSQL) | Semantic search (auto-recall) |
| `docs/solutions/` | Structured problem-solution docs | Unbounded (files) | `search_files` (keyword) + `hindsight_recall` (semantic) |

Rules:
- Don't duplicate between layers — pick ONE layer per fact
- Structured solutions → `docs/solutions/` + Hindsight summary (Phase 4.5)
- Procedures/workflows → Skills (not Hindsight, not docs/solutions/)
- Credentials → 1Password (never Hindsight, never docs/solutions/)

## Extending the Pattern

This bridge pattern can be replicated for other file-based knowledge stores:
1. Write-side: `hindsight_retain` with a typed prefix (e.g. `DECISION:`, `INCIDENT:`)
2. Read-side: add `hindsight_recall` to the relevant skill's grounding/check step
3. Auto-surface: add a reflect query to the weekly digest script

The key invariant: the file is the detailed reference, Hindsight is the semantic pointer. Never duplicate full content into Hindsight.
