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

name, description, version, author, license, metadata

name	description	version	author	license	metadata
compound-learning	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.	1.0.0	Hermes Agent (merged from Every Inc compound-engineering ce-compound)	MIT	hermes tags related_skills learning documentation knowledge-management compound-engineering 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:

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

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:

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

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

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

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
• 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:

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