Skip to content

Commit a3f6a10

Browse files
rysweetUbuntuclaude
authored
feat(skills): Add session-learning skill for cross-session knowledge
* feat(skills): Add session-learning skill for cross-session knowledge Add new skill for capturing and injecting learnings across sessions: - Auto-extracts insights at session stop - Injects relevant learnings at session start via keyword matching - Five categories: errors, workflows, tools, architecture, debugging - /amplihack:learnings command for management - Complements DISCOVERIES.md with structured YAML storage Part of Issue #1611 Enhancement 4 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> * fix(session-learning): Fix typo in ranking formula documentation Corrects malformed markdown in SKILL.md line 135. Uses inline code formatting to preserve formula correctly. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> * fix(session-learning): Improve skill quality from 8/10 to 9/10 Improvements made: - Created _stats.yaml template file (was referenced but missing) - Replaced placeholder examples with realistic amplihack-relevant learnings: - errors.yaml: circular imports, YAML parsing errors - workflows.yaml: git worktrees, pre-commit verification - tools.yaml: Claude SDK timeout handling, uvx branch testing - architecture.yaml: brick philosophy, skills vs scenarios - debugging.yaml: import isolation, hook debugging - Added Error Handling section with: - YAML parsing error recovery with backup - Missing files auto-creation - Fail-safe design principles - Added Hook Integration section with: - Complete stop hook example for learning extraction - Complete session start hook example for learning injection 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> * fix(docs): Fix formula formatting in session-learning README 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> --------- Co-authored-by: Ubuntu <azureuser@amplihack2.yb0a3bvkdghunmsjr4s3fnfhra.phxx.internal.cloudapp.net> Co-authored-by: Claude <[email protected]>
1 parent adaf4a5 commit a3f6a10

File tree

9 files changed

+1294
-0
lines changed

9 files changed

+1294
-0
lines changed

‎.claude/commands/amplihack/learnings.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
---
2+
description: View and manage cross-session learnings
3+
arguments:
4+
- name: action
5+
description: "Action to perform: show, search, add, stats"
6+
required: false
7+
- name: query
8+
description: "Category name or search query"
9+
required: false
10+
---
11+
12+
# /amplihack:learnings Command
13+
14+
Manage cross-session learnings stored in `.claude/data/learnings/`.
15+
16+
## Actions
17+
18+
### show [category]
19+
20+
Display learnings from all categories or a specific category.
21+
22+
**Categories:** errors, workflows, tools, architecture, debugging
23+
24+
**Examples:**
25+
26+
- `/amplihack:learnings show` - Show all learnings
27+
- `/amplihack:learnings show errors` - Show only error learnings
28+
29+
### search <query>
30+
31+
Search across all learning categories for matching keywords.
32+
33+
**Examples:**
34+
35+
- `/amplihack:learnings search import` - Find learnings about imports
36+
- `/amplihack:learnings search circular dependency` - Multi-word search
37+
38+
### add
39+
40+
Interactively add a new learning. You will be prompted for:
41+
42+
- Category (errors/workflows/tools/architecture/debugging)
43+
- Keywords (comma-separated)
44+
- Summary (one sentence)
45+
- Insight (detailed explanation)
46+
- Example (optional code)
47+
48+
### stats
49+
50+
Show learning statistics:
51+
52+
- Total learnings per category
53+
- Most used learnings
54+
- Recently added learnings
55+
- Average confidence scores
56+
57+
## Execution
58+
59+
When this command is invoked:
60+
61+
1. **Parse action and query** from arguments
62+
2. **Load learning files** from `.claude/data/learnings/`
63+
3. **Execute requested action**:
64+
65+
### For `show`:
66+
67+
```python
68+
# Read all YAML files in learnings directory
69+
# Filter by category if specified
70+
# Format learnings as readable markdown table
71+
72+
For each learning:
73+
Display:
74+
- ID and category
75+
- Keywords (comma-separated)
76+
- Summary
77+
- Confidence score
78+
- Times used
79+
```
80+
81+
### For `search`:
82+
83+
```python
84+
# Extract keywords from query
85+
# Search across all category files
86+
# Score matches by keyword overlap
87+
# Return sorted results with context
88+
89+
For each match:
90+
Display:
91+
- Category and ID
92+
- Match score (percentage)
93+
- Summary
94+
- Full insight (if high score)
95+
```
96+
97+
### For `add`:
98+
99+
```python
100+
# Ask user for category
101+
# Ask for keywords (suggest based on context)
102+
# Ask for one-sentence summary
103+
# Ask for detailed insight
104+
# Ask for example (optional)
105+
# Generate unique ID
106+
# Append to appropriate YAML file
107+
# Update last_updated timestamp
108+
```
109+
110+
### For `stats`:
111+
112+
```python
113+
# Load all learning files
114+
# Calculate:
115+
# - Count per category
116+
# - Total learnings
117+
# - Average confidence
118+
# - Most used (by times_used)
119+
# - Recently added (last 5 by created date)
120+
# Display formatted statistics
121+
```
122+
123+
## Output Format
124+
125+
### Show Output
126+
127+
```markdown
128+
## Learnings: [Category or All]
129+
130+
| ID | Keywords | Summary | Confidence |
131+
| ------- | ---------------- | ---------------------------------- | ---------- |
132+
| err-001 | import, circular | Circular imports cause ImportError | 0.9 |
133+
| wf-002 | git, worktree | Use worktrees for parallel work | 0.85 |
134+
135+
**Total:** X learnings across Y categories
136+
```
137+
138+
### Search Output
139+
140+
```markdown
141+
## Search Results for: "[query]"
142+
143+
### 1. [Category]: [Summary] (Match: 85%)
144+
145+
**Keywords:** import, circular, dependency
146+
**Insight:** [First 200 chars]...
147+
148+
### 2. [Category]: [Summary] (Match: 60%)
149+
150+
...
151+
152+
**Found:** X matching learnings
153+
```
154+
155+
### Stats Output
156+
157+
```markdown
158+
## Learning Statistics
159+
160+
| Category | Count | Avg Confidence |
161+
| ------------ | ----- | -------------- |
162+
| errors | 12 | 0.82 |
163+
| workflows | 8 | 0.78 |
164+
| tools | 5 | 0.85 |
165+
| architecture | 3 | 0.90 |
166+
| debugging | 7 | 0.75 |
167+
168+
**Total:** 35 learnings
169+
170+
### Most Used
171+
172+
1. err-003: "Circular imports cause ImportError" (used 15 times)
173+
2. wf-001: "Use pre-commit before push" (used 12 times)
174+
175+
### Recently Added
176+
177+
1. dbg-007: "Check Docker logs first" (2025-11-25)
178+
2. tool-004: "Use --verbose for debugging" (2025-11-24)
179+
```
180+
181+
## Related Files
182+
183+
- `.claude/data/learnings/errors.yaml` - Error patterns
184+
- `.claude/data/learnings/workflows.yaml` - Workflow insights
185+
- `.claude/data/learnings/tools.yaml` - Tool patterns
186+
- `.claude/data/learnings/architecture.yaml` - Design decisions
187+
- `.claude/data/learnings/debugging.yaml` - Debug strategies
188+
- `.claude/skills/session-learning/SKILL.md` - Full skill documentation

‎.claude/data/learnings/_stats.yaml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Session Learning Statistics
2+
# Auto-generated file tracking learning system usage metrics
3+
# Updated automatically when learnings are injected or extracted
4+
5+
stats:
6+
# Total learnings across all categories
7+
total_learnings: 0
8+
9+
# Learnings per category
10+
by_category:
11+
errors: 0
12+
workflows: 0
13+
tools: 0
14+
architecture: 0
15+
debugging: 0
16+
17+
# Injection statistics
18+
injections:
19+
total: 0
20+
sessions_with_injection: 0
21+
avg_learnings_per_session: 0.0
22+
23+
# Extraction statistics
24+
extractions:
25+
total: 0
26+
sessions_with_extraction: 0
27+
28+
# Effectiveness metrics
29+
effectiveness:
30+
# How often injected learnings were marked as helpful
31+
helpful_rate: 0.0
32+
# Learnings that have been used 3+ times
33+
proven_learnings: 0
34+
35+
# Last updated timestamp
36+
last_updated: "2025-11-25T00:00:00Z"
37+
38+
# Usage tracking by date (rolling 30 days)
39+
daily_usage: []
40+
# Example entry:
41+
# - date: "2025-11-25"
42+
# injections: 2
43+
# extractions: 1
44+
# helpful_count: 1

‎.claude/data/learnings/architecture.yaml‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Cross-Session Learning: Architecture Decisions
2+
# This file stores architecture decisions, trade-offs, and design insights.
3+
4+
category: architecture
5+
description: Architecture decisions, design trade-offs, and structural insights
6+
last_updated: "2025-11-25T00:00:00Z"
7+
8+
learnings:
9+
# Real example: Brick philosophy for modules
10+
- id: "arch-001"
11+
created: "2025-11-25T00:00:00Z"
12+
keywords:
13+
- "module"
14+
- "brick"
15+
- "design"
16+
- "interface"
17+
- "public"
18+
summary: "Design modules as self-contained bricks with explicit public interfaces"
19+
insight: |
20+
Following the brick philosophy: each module should be a self-contained
21+
unit with a clear public interface defined via __all__. This enables:
22+
- Independent testing without mocking internal details
23+
- Easy regeneration from specifications
24+
- Clear contracts for other modules to depend on
25+
26+
The "studs" (public API) should be stable while internal implementation
27+
can change freely.
28+
example: |
29+
# module/__init__.py - defines the public interface
30+
from .core import process, validate
31+
from .models import InputModel, OutputModel
32+
33+
__all__ = ["process", "validate", "InputModel", "OutputModel"]
34+
35+
# Internal functions stay private (not in __all__)
36+
# _internal_helper() in core.py is not exported
37+
confidence: 0.95
38+
times_used: 0
39+
40+
# Real example: Skills vs scenarios distinction
41+
- id: "arch-002"
42+
created: "2025-11-25T00:00:00Z"
43+
keywords:
44+
- "skill"
45+
- "scenario"
46+
- "tool"
47+
- "claude"
48+
- "capability"
49+
summary: "Skills are Claude capabilities, scenarios are executable tools"
50+
insight: |
51+
When user asks for "a tool", distinguish between:
52+
53+
1. **Skills** (.claude/skills/): Markdown docs that give Claude new
54+
capabilities. Loaded automatically when relevant. NOT executable.
55+
56+
2. **Scenarios** (.claude/scenarios/): Actual executable Python tools
57+
that users run via Makefile or command line.
58+
59+
The pattern: Build the executable tool first (scenario), optionally
60+
add a skill that knows how to use it effectively.
61+
example: |
62+
# User says: "Create a PDF analysis tool"
63+
64+
# Step 1: Build executable scenario
65+
.claude/scenarios/pdf-analyzer/
66+
tool.py # The actual tool
67+
tests/ # Tests
68+
README.md # Usage docs
69+
70+
# Step 2: Optionally add skill for Claude
71+
.claude/skills/pdf/SKILL.md # Tells Claude how to use the tool
72+
confidence: 0.9
73+
times_used: 0

‎.claude/data/learnings/debugging.yaml‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Cross-Session Learning: Debugging Strategies
2+
# This file stores debugging strategies, root cause patterns, and diagnostic techniques.
3+
4+
category: debugging
5+
description: Debugging strategies, root cause analysis, and diagnostic techniques
6+
last_updated: "2025-11-25T00:00:00Z"
7+
8+
learnings:
9+
# Real example: Isolating import issues
10+
- id: "dbg-001"
11+
created: "2025-11-25T00:00:00Z"
12+
keywords:
13+
- "import"
14+
- "debug"
15+
- "isolate"
16+
- "python"
17+
- "module"
18+
summary: "Use 'python -c' to isolate import errors from other code"
19+
insight: |
20+
When imports fail mysteriously (especially in larger codebases),
21+
isolate the problem by testing imports in a fresh Python process:
22+
23+
`python -c "import module_name"`
24+
25+
This removes interference from other imports, cached modules, or
26+
runtime state. The error message will be cleaner and point directly
27+
to the actual problem.
28+
example: |
29+
# Test a single import in isolation
30+
python -c "import problematic_module"
31+
32+
# Test a specific submodule
33+
python -c "from package.submodule import function"
34+
35+
# Check the import path
36+
python -c "import sys; print(sys.path)"
37+
confidence: 0.95
38+
times_used: 0
39+
40+
# Real example: Hook debugging strategy
41+
- id: "dbg-002"
42+
created: "2025-11-25T00:00:00Z"
43+
keywords:
44+
- "hook"
45+
- "claude"
46+
- "debug"
47+
- "log"
48+
- "session"
49+
summary: "Debug Claude Code hooks by checking runtime logs first"
50+
insight: |
51+
When hooks don't behave as expected:
52+
1. Check .claude/runtime/logs/ for session-specific logs
53+
2. Look for hook execution timestamps and outputs
54+
3. Verify hook is registered in settings.json
55+
4. Test hook function independently before integration
56+
57+
Hooks fail silently by design (to not break sessions), so logging
58+
is the primary debugging mechanism.
59+
example: |
60+
# Check recent session logs
61+
ls -lt .claude/runtime/logs/ | head -5
62+
63+
# View specific session log
64+
cat .claude/runtime/logs/2025-11-25_123456/hook_output.log
65+
66+
# Test hook function directly
67+
python -c "from hook_module import stop_hook; stop_hook(session_data)"
68+
confidence: 0.85
69+
times_used: 0

0 commit comments

Comments
 (0)