Initial commit: Hermes Agent Skills collection

2026-07-12 19:02:59 +00:00
commit e9cc106625
789 changed files with 233126 additions and 0 deletions
@@ -0,0 +1,277 @@
+---
+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.
@@ -0,0 +1,121 @@
+# Retrospective Session-Log Analysis
+
+Technique for applying compound-learning to past session logs — mining completed work for
+learnings that weren't captured at the time.
+
+## When to Use
+
+- User asks to "analyze recent sessions" or "apply compound-learning to session logs"
+- Periodic knowledge audit (e.g., weekly review of what was solved but not documented)
+- After a burst of activity where multiple sessions completed without individual compound-learning passes
+
+## Process
+
+### Step 1: Enumerate Recent Sessions
+
+Query the Hermes `state.db` directly (SQLite is in `~/.hermes/state.db`):
+
+```sql
+SELECT id, title, source, started_at, ended_at, message_count, tool_call_count,
+       estimated_cost_usd
+FROM sessions
+WHERE archived = 0
+ORDER BY started_at DESC
+LIMIT 10;
+```
+
+Column `id` is the session ID (TEXT). `started_at` is a Unix REAL timestamp.
+
+### Step 2: Extract Key Content Per Session
+
+For each session, extract:
+- **First user message** — the task/goal
+- **Last assistant message** — the resolution/outcome
+- **Tool usage counts** — `SELECT tool_name, COUNT(*) FROM messages WHERE session_id = ? GROUP BY tool_name`
+- **User messages** (skip system preambles like `[IMPORTANT:` and `[CONTEXT COMPACTION`)
+
+```sql
+SELECT id, role, content
+FROM messages
+WHERE session_id = ? AND content IS NOT NULL AND content != '' AND length(content) > 50
+ORDER BY id ASC;
+```
+
+**Note:** Some assistant messages have empty `content` but populated `tool_calls` (JSON). If
+content-based extraction yields thin results, check `tool_calls` column for the actual work.
+
+### Step 3: Classify Each Session
+
+Apply compound-learning Phase 2 classification:
+
+| Signal | Type | Worth a solution doc? |
+|---|---|---|
+| Bug fixed, root cause found | `bug-fix` | Yes, if non-trivial |
+| Architecture decision made | `architecture-pattern` | Yes |
+| Tool/library chosen or configured | `tooling-decision` | Yes |
+| Multi-step workflow executed | `workflow` | Yes, if reusable |
+| Third-party API/device integrated | `integration` | Yes |
+| Price search, research, Q&A | — | Usually no (one-off) |
+| Cron job ran successfully | — | Only if new failure mode discovered |
+
+**Skip sessions that are:** routine cron runs with no errors, pure research/Q&A, or
+sessions that ended inconclusively without a resolution.
+
+### Step 4: Write Solution Docs
+
+Follow compound-learning Phases 3-6 for each qualifying session:
+1. Overlap check: `search_files("keyword", path="docs/solutions/")`
+2. Write to `docs/solutions/{type}/{YYYY-MM-DD}-{slug}.md` with YAML frontmatter
+3. Cross-reference related docs (e.g., HA token expiry → HA SSH addon integration)
+4. Include the session ID in the References section for traceability
+
+### Step 5: Hindsight Sync (Phase 4.5)
+
+**Check daemon health FIRST:**
+```bash
+curl -s http://127.0.0.1:9177/health
+```
+
+If healthy: batch `hindsight_retain` for all solution docs.
+If down: skip Hindsight sync — `docs/solutions/` files are sufficient alone.
+
+### Step 6: Self-Improvement Routing (Phase 7)
+
+Review all solution docs collectively for systemic gaps:
+- Does a skill need a patch? (e.g., "always try SSH addon first for HA")
+- Does MEMORY.md need a durable fact? (check for overflow first!)
+- Is there a recurring failure pattern across multiple sessions?
+
+Present SI suggestions as a batch table to the user.
+
+## Pitfalls
+
+- **Don't write a solution doc for every session** — routine cron runs and one-off research don't qualify
+- **Include session IDs in References** — enables future `session_search(session_id=...)` deep-dives
+- **Cross-reference related solutions** — e.g., "HA token expiry" and "HA SSH addon integration" should link to each other
+- **MEMORY.md overflow** — batch SI suggestions may collectively exceed the 2,200 char limit. Check current usage before proposing multiple memory additions.
+- **Empty content fields** — some assistant messages store work in `tool_calls` JSON, not `content`. If extraction looks thin, query `tool_calls` as well.
+
+## SQLite Schema Reference
+
+```sql
+-- sessions table
+id TEXT PRIMARY KEY         -- session ID
+source TEXT                 -- 'telegram', 'cron', etc.
+started_at REAL             -- Unix timestamp
+ended_at REAL               -- Unix timestamp (nullable)
+message_count INTEGER
+tool_call_count INTEGER
+estimated_cost_usd REAL
+title TEXT                  -- session title (nullable)
+archived INTEGER DEFAULT 0
+
+-- messages table
+id INTEGER PRIMARY KEY
+session_id TEXT             -- FK to sessions.id
+role TEXT                   -- 'user', 'assistant', 'tool'
+content TEXT                -- message text (may be empty for tool-call-only turns)
+tool_calls TEXT             -- JSON array of tool calls
+tool_name TEXT              -- tool name (for role='tool' rows)
+timestamp REAL
+```
@@ -0,0 +1,115 @@
+# Self-Improvement Loop Architecture
+
+The closed-loop system connecting compound-learning, Hindsight, and skill/memory self-improvement.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     PROBLEM SOLVED                          │
+└──────────────────────────┬──────────────────────────────────┘
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│  compound-learning                                          │
+│  ├─ Phase 1-3: Identify, classify, overlap-check             │
+│  ├─ Phase 4: Write solution doc → docs/solutions/{type}/     │
+│  ├─ Phase 4.5: Hindsight sync (hindsight_retain)             │
+│  │   └─ Summary + tags + source path → PostgreSQL            │
+│  ├─ Phase 5-6: CONCEPTS.md, discoverability                  │
+│  └─ Phase 7: Self-Improvement Routing                        │
+│      ├─ Skill gap? → skill_manage(patch) [ASK USER]          │
+│      ├─ Memory gap? → memory(add)                            │
+│      ├─ Instruction file gap? → patch(file) [ASK USER]       │
+│      └─ Track: hindsight_retain(tags=["self-improvement"])   │
+└──────────────────────────┬──────────────────────────────────┘
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│  GROUNDING SCANS (next session)                              │
+│  ├─ brainstorming Step 1.5: search_files + hindsight_recall   │
+│  ├─ plan Step 1.5: search_files + hindsight_recall            │
+│  └─ writing-plans Step 1.5: search_files + hindsight_recall   │
+│      └─ Semantic search finds solutions even when keywords    │
+│         don't match (e.g. "Galera bootstrap" → "SST Recovery")│
+└──────────────────────────┬──────────────────────────────────┘
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│  META-MEMORY AUTOMATION (cronjobs)                           │
+│                                                              │
+│  Nightly Dream (0 3 * * *)                                  │
+│  ├─ Contradiction detection                                  │
+│  ├─ Blocked/stale TODOs                                      │
+│  ├─ Outdated facts                                           │
+│  └─ Self-improvement: learnings vs. existing skills           │
+│                                                              │
+│  Weekly Digest (0 8 * * 0)                                   │
+│  ├─ Recurring patterns                                       │
+│  ├─ Infra changes                                            │
+│  ├─ Open TODOs                                               │
+│  ├─ Recommendations                                          │
+│  ├─ Solution patterns (compound-learning)                    │
+│  └─ Self-improvement audit (open vs. acted-on)               │
+│                                                              │
+│  Monthly Cleanup (0 3 1 * *)                                 │
+│  └─ Dedup + decay report                                     │
+└──────────────────────────────────────────────────────────────┘
+```
+
+## Three-Tier Memory Strategy
+
+| Layer | Scope | Capacity | Retrieval |
+|---|---|---|---|
+| MEMORY.md | Hot facts, TODOs, quick refs | ~2,200 chars | Injected every turn (always visible) |
+| Hindsight (PostgreSQL) | Unlimited detail, history, context | Unbounded | Semantic search (auto-recall) |
+| `docs/solutions/` | Structured problem-solution docs | Unbounded (files) | `search_files` (keyword) + `hindsight_recall` (semantic via Phase 4.5) |
+
+**Routing rule:** One fact, one layer. Don't duplicate.
+- Short pointers → MEMORY.md
+- Full detail → Hindsight
+- Structured solutions (root cause + fix + lesson + prevention) → `docs/solutions/` + Hindsight summary
+- Recurring procedures → Skills
+- Credentials → 1Password
+
+## Phase 4.5: Hindsight Sync
+
+After writing a solution doc, 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",
+    tags=["solution"] + tags
+)
+```
+
+Graceful degradation: if Hindsight daemon is down (`curl -s http://127.0.0.1:9177/health` fails),
+the file in `docs/solutions/` is sufficient on its own.
+
+## Phase 7: Self-Improvement Routing
+
+Decision tree for when a learning reveals a system gap:
+
+| Learning implies... | Action | Tool | Mode |
+|---|---|---|---|
+| Skill has wrong/missing/outdated step | Patch skill | `skill_manage(action='patch')` | Ask user |
+| No skill for recurring workflow | Propose new skill | `skill_manage(action='create')` | Ask user |
+| Durable environment fact | Update MEMORY.md | `memory` tool | Just do it |
+| Tool quirk/workaround | Update MEMORY.md | `memory` tool | Just do it |
+| Convention change (AGENTS.md/CLAUDE.md) | Patch instruction file | `patch` tool | Ask user |
+
+Tracking: every SI suggestion is stored via `hindsight_retain(tags=["self-improvement"])` so the
+weekly digest can audit what was acted on vs. what's still open.
+
+## Files Modified (Integration Points)
+
+| File | Change |
+|---|---|
+| `compound-learning/SKILL.md` | Phase 4.5 (Hindsight sync), Phase 7 (SI routing), updated integrations + frontmatter |
+| `brainstorming/SKILL.md` | Step 1.5 Grounding Scan: + `hindsight_recall` |
+| `plan/SKILL.md` | Step 1.5 Grounding Scan: + `hindsight_recall` |
+| `writing-plans/SKILL.md` | Step 1.5 Grounding Scan: + `hindsight_recall` |
+| `optimize-loops/SKILL.md` | Phase 5: note about Phase 4.5 Hindsight sync |
+| `hindsight/SKILL.md` | Three-tier strategy, SI loop documentation, cronjob descriptions updated |
+| `hindsight/scripts/hindsight_nightly_dream.py` | Check #4: self-improvement suggestions |
+| `hindsight/scripts/hindsight_weekly_digest.py` | Section #5: solution patterns, #6: SI audit |