terraphim/terraphim-ai/learning-capture

Learning Capture

Use this skill to automatically capture failed commands and their error output as learning documents. Build a personal knowledge base of common mistakes and solutions.

When to Use

• When commands fail and you want to remember the fix
• To build up a searchable database of common errors
• For tracking patterns across multiple projects
• When onboarding team members (share common pitfalls)
• To reduce time spent debugging the same issues

How It Works

1. Capture - Records failed commands with error context
2. Redact - Automatically removes secrets (API keys, passwords)
3. Store - Saves as Markdown in .terraphim/learnings/ or ~/.local/share/terraphim/learnings/
4. Index - Makes learnings searchable via knowledge graph
5. Retrieve - Query past failures to find solutions

Quick Start

Manual Capture

# After a command fails, capture it manually
terraphim-agent learn capture "git push -f" \
  --error "remote: rejected" \
  --exit-code 1
 
# Output: Captured learning: .terraphim/learnings/learning-abc123.md

Automatic Capture via Hook

Enable automatic capture of all failed Bash commands:

# Add to .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": {
          "tools": ["BashTool"]
        },
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/learning-capture.sh"
          }
        ]
      }
    ]
  }
}

From then on, every failed command is automatically captured.

Usage

Capture a Failed Command

terraphim-agent learn capture <command> --error <errmsg> [--exit-code N]

Parameters:

• command - The command that failed (required)
• --error - Error message or stderr output (required)
• --exit-code - Exit code (default: 1)
• --debug - Show debug output

Example:

terraphim-agent learn capture "npm install" \
  --error "EACCES: permission denied, mkdir '/node_modules'" \
  --exit-code 243

List Recent Learnings

# Show last 10 learnings (default)
terraphim-agent learn list
 
# Show more
terraphim-agent learn list --recent 20
 
# Show global learnings
terraphim-agent learn list --global

Output:

Recent learnings:
  1. [P] git push -f (exit: 1)
  2. [G] npm install (exit: 243)
  3. [P] cargo build (exit: 101)
     Correction: cargo build --release

[P] = Project-specific | [G] = Global

Query Learnings

# Search by substring
terraphim-agent learn query "git push"
 
# Exact match
terraphim-agent learn query "git push -f" --exact
 
# Search global only
terraphim-agent learn query "npm" --global

Storage Locations

Learnings are stored as Markdown files:

Project-Specific (.terraphim/learnings/)

• Created when in a project directory
• Priority for project-specific queries
• Committed with project (optional)

Global (~/.local/share/terraphim/learnings/)

• Fallback location
• Common patterns across all projects
• Never committed

Secret Redaction

Before storage, the system automatically redacts:

Ignored Commands

The following are automatically ignored (not captured):

• cargo test* - Rust tests
• npm test* - Node tests
• pytest* - Python tests
• yarn test* - Yarn tests

Configuration

Environment Variables

Hook Configuration

Create or edit .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": {
          "tools": ["BashTool"]
        },
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/learning-capture.sh"
          }
        ]
      }
    ]
  }
}

Learning Document Format

Each learning is stored as Markdown with YAML frontmatter:

---
id: abc123-1708012345678
command: git push -f
exit_code: 1
source: Project
captured_at: 2024-01-15T10:30:00Z
working_dir: /home/user/myproject
tags:
  -learning
  -exit-1
---
 
## Command
 
`git push -f`
 
## Error Output
 

remote: rejected

Best Practices

1. Review Before Capture - Check that error output doesn't contain sensitive info
2. Add Corrections - When you find the fix, add it to the learning
3. Query Regularly - Before asking for help, search your learnings
4. Clean Up - Periodically remove outdated learnings
5. Share Common Patterns - Commit project learnings to help teammates

Troubleshooting

Integration Examples

With Shell Aliases

# Add to .bashrc or .zshrc
alias learn='terraphim-agent learn'
alias learnc='terraphim-agent learn capture'
alias learnl='terraphim-agent learn list'
alias learnq='terraphim-agent learn query'
 
# Usage
learn capture "cmd" --error "msg"
learnl --recent 5
learnq "git push"

With Git

# Show learnings for current project
git rev-parse --show-toplevel | xargs -I {} terraphim-agent learn list
 
# Commit learnings with project
git add .terraphim/learnings/
git commit -m "docs: add common error patterns"

With Makefile

# Capture failed commands in CI
learn:
	@terraphim-agent learn list --recent 10
 
.PHONY: learn

Future Enhancements

Coming in future releases:

• Auto-suggest corrections - Query KG for suggested fixes
• Web UI - Browse and manage learnings visually
• Export/Import - Share between machines
• Team sharing - Common patterns for teams
• Statistics - Most common errors, success rates

Related Skills

• smart-commit - Enhance commits with knowledge graph concepts
• pre-llm-validate - Validate input before LLM calls
• post-llm-check - Validate LLM outputs against checklists
• terraphim-hooks - Full hooks documentation

See Also

• Learning System Documentation
• Knowledge Graph Overview
• CLI Reference

Appendix: Traceability Matrix

This matrix maps skill examples to implementation status and verification evidence.

Quick Start Examples

Usage Examples

Configuration Examples

Feature Status

Verification Status

• Unit Tests: 15/15 passing ✅
• Integration Tests: All passing ✅
• Documentation: Complete ✅
• Examples Verified: 22/22 ✅ (100%)
• Code Quality: Formatted, no clippy warnings ✅

Reports

• Phase 4 Verification Report
• Phase 5 Validation Report

Last Verified: 2026-02-15