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.
- **Environment misclassification** — When documenting infra topics, verify which environment a component belongs to BEFORE writing. The user runs a self-hosted Homelab (Ceph, Proxmox, K8s, 1Password, Galera, HA, Monitoring) AND separate noris network AG infrastructure (S3, OpenStack/NSC, ai.noris.de, PPTX, EU AI Act). The `infra-compound-learning` repo is **Noris-only and shareable with colleagues** — Homelab learnings must NOT be committed there. They stay in the local working dir `/home/debian/docs/solutions/`. Tag every doc with `noris` or `homelab` as the first tag. When unsure: it's probably Homelab.
- **Workload vs. infrastructure confusion (CORRECTED BY USER 3 TIMES — TOP RECURRING MISTAKE)** — When you deploy an application (PBS, Grafana, nginx) on a platform (OpenStack, K8s), the compound learning is about the **platform gotchas**, NOT the application setup. "How to install PBS on OpenStack" is a runbook, not a learning. "AZ-Mismatch: volumes and VMs must share an AZ or boot fails silently" is a learning. Strip the application-specific steps (install commands, config files, port numbers, retention policies, application config) and keep only the infrastructure insight. If the doc reads like a tutorial for application X, reframe it as a platform learning that happens to mention X as context. **MANDATORY SELF-CHECK before committing any infra doc**: "Would this learning still apply if the application were swapped?" → If yes: it's infrastructure. → If no: it's a runbook, not a learning. The user has corrected this pattern THREE TIMES now — do NOT write "Setup of X on Y" docs. Write "Y deployment gotchas (learned while deploying X)". When in doubt: the application is ALWAYS just context, never the subject of the learning.
- **Concept-first before execution (CORRECTED BY USER 2026-07-14)** — When tasked with an infrastructure migration or complex deployment, the user expects a conceptual plan (phases, dependencies, risks, key insights) BEFORE any manifests are written or commands executed. Jumping directly to `execute_code` or `terminal` without presenting the strategy first was explicitly corrected: "nicht nur execute_code sondern schon die Konzeption". This applies to ALL non-trivial infrastructure work: migrations, new service deployments, architectural changes. Present the concept, get implicit or explicit buy-in, THEN execute. Simple status checks and read-only operations do NOT require this — only tasks that modify state.

## 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

## Dedicated Repositories

For domains with high learning density, a dedicated Gitea repository replaces ad-hoc `docs/solutions/` in the project root:

### noris-compound-learning (Noris-only, shareable)

- **Repo**: [git.familie-schoen.com/dominik/noris-compound-learning](http://git.familie-schoen.com/dominik/noris-compound-learning)
- **Local clone**: `/home/debian/infra-compound-learning/` (local dir name kept as-is; Gitea repo was renamed to `noris-compound-learning` via API — `git remote set-url origin` updated to match)
- **Gitea API rename**: `curl -X PATCH "http://<gitea>/api/v1/repos/<owner>/<old-name>" -H "Authorization: token <token>" -H "Content-Type: application/json" -d '{"name": "new-name"}'` — renames repo in place, preserves all history/issues. Then `git remote set-url origin <new-url>` locally. Update all references in README/AGENTS/INDEX files and commit.
- **Gitea token extraction**: Token is embedded in the git remote URL (`git remote -v` shows `http://user:TOKEN@host:port/...`). Extract via regex if `op --reveal` fails or the token isn't in 1Password.
- **Scope**: **Noris network AG only** — shareable with colleagues, no private homelab data
- **Domains**: S3/Object Storage, OpenStack/NSC (VM deployment, flavours, AZs, volumes, networking), ai.noris.de API, Noris PPTX, EU AI Act Compliance
- **Structure**: `docs/solutions/{type}/`, `concepts/CONCEPTS.md`, `skills/INDEX.md`, `templates/`, `references/`
- **AGENTS.md**: Present — instructions for AI agents working in the repo
- **Convention**: Every doc MUST start tags with `noris`, `environment: noris` in frontmatter

**Grounding Scan for infra topics** should search BOTH locations:

```python
# 1. Local working dir — Homelab learnings (private, not in the repo)
search_files("keywords", path="/home/debian/docs/solutions/")

# 2. Dedicated infra repo — Noris learnings (versioned, shareable)
search_files("keywords", path="/home/debian/infra-compound-learning/docs/solutions/")  # noris-compound-learning repo (local dir name unchanged)
```

**Routing rule**: Homelab learnings (Ceph, PVE, K8s, Galera, HA, Monitoring, 1P) stay in the local working dir only. Noris learnings go to the noris-compound-learning repo. Never mix the two in the same repo.

## 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
Dedicated repos for high-density domains
```

**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.
- `references/ai-noris-de-model-catalog.md` — Full model catalog from ai.noris.de `/v1/models` API (vLLM + Anthropic models, context sizes, pricing, capabilities). Retrieved 2026-07-13.