hermes-skills/software-development/compound-learning/SKILL.md

---
name: compound-learning
description: "Capture learnings from solved problems into docs/solutions/ so future plans start smarter. Use after completing a debugging session, feature implementation, or fixing a tricky issue."
version: 1.0.0
author: Hermes Agent (merged from Every Inc compound-engineering ce-compound)
license: MIT
metadata:
  hermes:
    tags: [learning, documentation, knowledge-management, compound-engineering]
    related_skills: [brainstorming, plan, writing-plans, systematic-debugging, subagent-driven-development, optimize-loops, hindsight]
---

# Compound Learning

Capture problem solutions while context is fresh, creating structured documentation in `docs/solutions/` with YAML frontmatter for searchability and future reference.

**Why "compound"?** Each documented solution compounds your team's knowledge. The first time you solve a problem takes research. Document it, and the next occurrence takes minutes. Knowledge compounds.

## Universal Grounding Scan (Mandatory Pre-Step)

**Before starting ANY new task**, run a Grounding Scan to find relevant past solutions:

```python
# 1. Keyword search in solution docs
search_files("keywords from the task description", path="docs/solutions/")

# 2. Semantic search in Hindsight (if daemon healthy)
hindsight_recall("natural language description of the task topic")
```

This is non-negotiable for all tasks, not just brainstorming/plan/writing-plans.
Even simple-looking tasks may have a prior solution that saves 30+ minutes.

**Skip only if:** the task is a continuation of the current task in the same session
(context already loaded) or a trivial greeting/meta-question.

## When to Use

- After solving a non-trivial bug or debugging session
- After completing a feature that revealed a pattern or gotcha
- When you discover something that would save 30+ minutes next time
- After any task where you thought "I wish I'd known this before starting"

**Skip for:** trivial fixes (typo, import order), one-off tasks unlikely to recur, obvious changes.

## The Process

### Phase 1: Identify the Learning

Ask yourself:
1. What was the problem? (one sentence)
2. What was the root cause? (one sentence)
3. What was the fix? (one sentence)
4. What's the reusable insight? (the part that helps next time)

If you can't answer all four, the learning isn't ripe yet — finish understanding the problem first.

### Phase 2: Classify the Learning

Classify by problem type — this determines the directory and searchability:

| Type | Directory | Examples |
|---|---|---|
| `bug-fix` | `docs/solutions/bug-fixes/` | Race condition, off-by-one, env-specific failure |
| `architecture-pattern` | `docs/solutions/architecture/` | Service boundary decision, caching strategy |
| `tooling-decision` | `docs/solutions/tooling/` | Library choice, framework upgrade approach |
| `workflow` | `docs/solutions/workflows/` | Deployment process, testing strategy |
| `integration` | `docs/solutions/integrations/` | Third-party API quirk, auth flow |

### Phase 3: Check for Overlap

Before writing, search for existing docs that might cover the same topic:

```python
search_files("keyword_from_problem", path="docs/solutions/")
```

- If a near-duplicate exists: update it instead of creating a new one
- If a related doc exists with a different angle: cross-reference it in the new doc
- If no match: proceed to write

### Phase 4: Write the Solution Doc

Create the file with this structure:

```markdown
---
title: "[Problem summary]"
date: YYYY-MM-DD
problem_type: bug-fix|architecture-pattern|tooling-decision|workflow|integration
tags: [tag1, tag2]
severity: low|medium|high
status: active
---

# [Problem Summary]

## Context
What were you trying to do? What was the environment?

## Problem
What went wrong? What were the symptoms?

## Root Cause
Why did it happen? Trace the actual cause, not just the symptom.

## Solution
What was the fix? Include code snippets if relevant.

## Lesson
What's the reusable insight? What would you do differently next time?

## Prevention
How to avoid this in the future? (lint rule, test, CI check, convention)

## References
- Links to related docs, PRs, issues, external resources
```

Save to: `docs/solutions/{type}/{YYYY-MM-DD}-{slug}.md`

### Phase 4.5: Hindsight Sync (Semantic Indexing)

After writing the solution doc, sync the key learning to Hindsight for semantic search.
This bridges file-based solutions with Hindsight's vector search — future Grounding Scans
find this learning even without knowing the exact filename or keywords.

```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
)
```

**What goes where:**

| Layer | Content | Retrieval |
|---|---|---|
| `docs/solutions/` file | Full detail: context, code, prevention | `search_files` (keyword) |
| Hindsight | Compact summary + tags + source path | `hindsight_recall` (semantic) |

The file is the detailed reference; Hindsight holds the semantic pointer.
Don't duplicate the full doc into Hindsight — just the summary.

**Skip Hindsight sync if:** Hindsight daemon is down (check `curl -s http://127.0.0.1:9177/health`).
The file in `docs/solutions/` is always sufficient on its own.

### Phase 5: Vocabulary Capture (CONCEPTS.md)

If the learning introduced or clarified a domain term:

1. Check if `CONCEPTS.md` exists in the repo root
2. If the term isn't already there, add it with a one-line definition
3. Link to the solution doc for the full story

```markdown
## Concept Name
Brief definition. See [solution doc](docs/solutions/...) for context.
```

### Phase 6: Discoverability Check

Ensure future agents will find this learning:

1. Is the doc in `docs/solutions/`? (the `brainstorming` and `plan` skills search there)
2. Are the tags searchable? (use terms someone would search for)
3. Is `CONCEPTS.md` updated if relevant?
4. If a project instruction file exists (`AGENTS.md`, `CLAUDE.md`), add a one-line pointer if the learning changes a convention

### Phase 7: Self-Improvement Routing (Closing the Loop)

The strongest form of compound learning is updating the system itself. Check whether this learning
implies a change to skills, memory, or conventions:

**Decision tree:**

| Learning implies... | Action | Tool |
|---|---|---|
| A skill has a wrong/missing/outdated step | Patch the skill | `skill_manage(action='patch')` |
| A skill doesn't exist for a recurring workflow | Propose new skill | Ask user, then `skill_manage(action='create')` |
| A durable environment fact or convention | Update MEMORY.md | `memory` tool |
| A tool quirk or workaround worth remembering | Update MEMORY.md | `memory` tool |
| A convention change affecting AGENTS.md/CLAUDE.md | Patch the instruction file | `patch` tool |

**Rules:**
- Only route to self-improvement if the learning reveals a **gap** — not if it's just a project-specific solution
- Skill patches: quote the exact section that's wrong, provide the replacement. Follow the system prompt rule: "If a skill has issues, fix it with `skill_manage(action='patch')`"
- MEMORY.md: only durable facts, not task-specific details. Check for overflow first.
- **Always ask the user before patching skills or instruction files** (per ABSOLUTE RULES)
- In headless mode: emit a structured recommendation instead of auto-patching

**Interactive mode — present as:**
```
This learning suggests a self-improvement:
  → Skill 'systematic-debugging' Step 3 is missing the bisection harness option
  → Patch it now? (recommended / skip)
```

**Headless mode — emit:**
```yaml
self_improvement:
  type: skill_patch | memory_update | new_skill | instruction_file
  target: "skill-name or MEMORY.md"
  description: "What's wrong and what to change"
  priority: high | medium | low
```

Track self-improvement actions via `hindsight_retain` with tag `["self-improvement"]` so the
weekly digest can audit what was acted on vs. what's still open.

## Modes

### Interactive (default)
Present options to the user:
```
1. Full (recommended) — research, cross-reference, and review the learning
2. Lightweight — single pass, faster, no overlap check
```

### Headless (for automations)
No blocking questions. Run Full mode without session history. Apply discoverability silently. End with a structured report.

Trigger headless mode when invoked from another skill (e.g., `subagent-driven-development` auto-compound after task completion).

## Pitfalls

- **One learning per run** — don't batch multiple distinct learnings into one doc
- **Don't document trivia** — if it won't save time next time, skip it
- **Don't skip the overlap check** — duplicate docs fragment knowledge
- **Don't forget the tags** — untagged docs are unfindable
- **Write for the next agent, not for yourself** — the reader has zero context
- **Check Hindsight daemon health BEFORE batch retain** — Phase 4.5 says to check `curl -s http://127.0.0.1:9177/health` first, but it's tempting to fire multiple `hindsight_retain` calls in parallel for efficiency. If the daemon is down, ALL calls fail and trigger loop-warning penalties. Always: one health check → then batch retains. The `docs/solutions/` files are sufficient alone if Hindsight is unavailable.

## Integration with Other Skills

- **ALL skills** — Universal Grounding Scan (see section above) runs before any task
- **brainstorming** — Phase 1.5 Grounding Scan reads `docs/solutions/` + queries `hindsight_recall`
- **plan** — Step 1.5 Grounding Scan reads `docs/solutions/` + queries `hindsight_recall`
- **writing-plans** — Step 1.5 Grounding Scan reads `docs/solutions/` + queries `hindsight_recall`
- **systematic-debugging** — after Phase 4 (fix), invoke compound-learning to capture
- **subagent-driven-development** — Step 5 auto-compounds after task completion
- **optimize-loops** — Phase 5 saves final summary to `docs/solutions/` + Hindsight
- **hindsight** — Phase 4.5 syncs solution summary to Hindsight for semantic search; weekly digest auto-surfaces solution patterns

## Hermes Agent Integration

Use Hermes tools throughout:
- `search_files` — find existing solutions and overlap
- `read_file` — read existing docs for cross-referencing
- `write_file` — create the solution doc
- `terminal` — git operations (commit the learning)
- `delegate_task` — optionally dispatch a research subagent for complex learnings
- `hindsight_retain` — sync solution summary to Hindsight (Phase 4.5) for semantic discoverability
- `hindsight_recall` — used by Grounding Scans in other skills to find this solution later

## Remember

```
One learning per doc
Reusable insight, not just the fix
Tags for searchability
Overlap check before writing
CONCEPTS.md for vocabulary
Hindsight sync for semantic findability
Self-improvement routing closes the loop
```

**Knowledge compounds — but only if you capture it. And the strongest compound is fixing the system itself.**

## Further Reading

- `references/self-improvement-loop.md` — Full architecture diagram of the closed-loop system: compound-learning → Hindsight → meta-memory cronjobs → self-improvement routing → next-session grounding scans.
- `references/retrospective-session-analysis.md` — Technique for mining past session logs from `state.db` (SQLite) to retroactively capture learnings that weren't documented at the time. Includes SQL schema reference and classification criteria.