scooter-lacroix/compound-learnings

Compound Learnings

Transform ephemeral session learnings into permanent, compounding capabilities.

When to Use

• "What should I learn from recent sessions?"
• "Improve my setup based on recent work"
• "Turn learnings into skills/rules"
• "What patterns should become permanent?"
• "Compound my learnings"

Process

Step 1: Gather Learnings

# List learnings (most recent first)
ls -t $CLAUDE_PROJECT_DIR/.maestro/cache/learnings/*.md | head -20

# Count total
ls $CLAUDE_PROJECT_DIR/.maestro/cache/learnings/*.md | wc -l

Read the most recent 5-10 files (or specify a date range).

Step 2: Extract Patterns (Structured)

For each learnings file, extract entries from these specific sections:

| Section Header | What to Extract | |----------------|-----------------| | ## Patterns or Reusable techniques | Direct candidates for rules | | **Takeaway:** or **Actionable takeaway:** | Decision heuristics | | ## What Worked | Success patterns | | ## What Failed | Anti-patterns (invert to rules) | | ## Key Decisions | Design principles |

Build a frequency table as you go:

| Pattern | Sessions | Category |
|---------|----------|----------|
| "Check artifacts before editing" | abc, def, ghi | debugging |
| "Pass IDs explicitly" | abc, def, ghi, jkl | reliability |

Step 2b: Consolidate Similar Patterns

Before counting, merge patterns that express the same principle:

Example consolidation:

• "Artifact-first debugging"
• "Verify hook output by inspecting files"
• "Filesystem-first debugging" → All express: "Observe outputs before editing code"

Use the most general formulation. Update the frequency table.

Step 3: Detect Meta-Patterns

Critical step: Look at what the learnings cluster around.

If >50% of patterns relate to one topic (e.g., "hooks", "tracing", "async"): → That topic may need a dedicated skill rather than multiple rules → One skill compounds better than five rules

Ask yourself: "Is there a skill that would make all these rules unnecessary?"

Step 4: Categorize (Decision Tree)

For each pattern, determine artifact type:

Is it a sequence of commands/steps?
  → YES → SKILL (executable > declarative)
  → NO ↓

Should it run automatically on an event (SessionEnd, PostToolUse, etc.)?
  → YES → HOOK (automatic > manual)
  → NO ↓

Is it "when X, do Y" or "never do X"?
  → YES → RULE
  → NO ↓

Does it enhance an existing agent workflow?
  → YES → AGENT UPDATE
  → NO → Skip (not worth capturing)

Artifact Type Examples:

| Pattern | Type | Why | |---------|------|-----| | "Run linting before commit" | Hook (PreToolUse) | Automatic gate | | "Extract learnings on session end" | Hook (SessionEnd) | Automatic trigger | | "Debug hooks step by step" | Skill | Manual sequence | | "Always pass IDs explicitly" | Rule | Heuristic |

Step 5: Apply Signal Thresholds

| Occurrences | Action | |-------------|--------| | 1 | Note but skip (unless critical failure) | | 2 | Consider - present to user | | 3+ | Strong signal - recommend creation | | 4+ | Definitely create |

Step 6: Propose Artifacts

Present each proposal in this format:

---

## Pattern: [Generalized Name]

**Signal:** [N] sessions ([list session IDs])

**Category:** [debugging / reliability / workflow / etc.]

**Artifact Type:** Rule / Skill / Agent Update

**Rationale:** [Why this artifact type, why worth creating]

**Draft Content:**
\`\`\`markdown
[Actual content that would be written to file]
\`\`\`

**File:** `.maestro/rules/[name].md` or `.maestro/skills/[name]/SKILL.md`

---

Use AskUserQuestion to get approval for each artifact (or batch approval).

Step 7: Create Approved Artifacts

For Rules:

# Write to rules directory
cat > $CLAUDE_PROJECT_DIR/.maestro/rules/<name>.md << 'EOF'
# Rule Name

[Context: why this rule exists, based on N sessions]

## Pattern
[The reusable principle]

## DO
- [Concrete action]

## DON'T
- [Anti-pattern]

## Source Sessions
- [session-id-1]: [what happened]
- [session-id-2]: [what happened]
EOF

For Skills:

Create .maestro/skills/<name>/SKILL.md with:

• Frontmatter (name, description, allowed-tools)
• When to Use
• Step-by-step instructions (executable)
• Examples from the learnings

Add triggers to skill-rules.json if appropriate.

For Hooks:

Create shell wrapper + TypeScript handler:

# Shell wrapper
cat > $CLAUDE_PROJECT_DIR/.maestro/hooks/<name>.sh << 'EOF'
#!/bin/bash
set -e
cd "$CLAUDE_PROJECT_DIR/.maestro/hooks"
cat | node dist/<name>.mjs
EOF
chmod +x $CLAUDE_PROJECT_DIR/.maestro/hooks/<name>.sh

Then create src/<name>.ts, build with esbuild, and register in settings.json:

{
  "hooks": {
    "EventName": [{
      "hooks": [{
        "type": "command",
        "command": "$CLAUDE_PROJECT_DIR/.maestro/hooks/<name>.sh"
      }]
    }]
  }
}

For Agent Updates:

Edit existing agent in .maestro/agents/<name>.md to add the learned capability.

Step 8: Summary Report

## Compounding Complete

**Learnings Analyzed:** [N] sessions
**Patterns Found:** [M]
**Artifacts Created:** [K]

### Created:
- Rule: `explicit-identity.md` - Pass IDs explicitly across boundaries
- Skill: `debug-hooks` - Hook debugging workflow

### Skipped (insufficient signal):
- "Pattern X" (1 occurrence)

**Your setup is now permanently improved.**

Quality Checks

Before creating any artifact:

1. Is it general enough? Would it apply in other projects?
2. Is it specific enough? Does it give concrete guidance?
3. Does it already exist? Check .maestro/rules/ and .maestro/skills/ first
4. Is it the right type? Sequences → skills, heuristics → rules

Files Reference

• Learnings: .maestro/cache/learnings/*.md
• Skills: .maestro/skills/<name>/SKILL.md
• Rules: .maestro/rules/<name>.md
• Hooks: .maestro/hooks/<name>.sh + src/<name>.ts + dist/<name>.mjs
• Agents: .maestro/agents/<name>.md
• Skill triggers: .maestro/skills/skill-rules.json
• Hook registration: .maestro/settings.json → hooks section