Skip to content

[RFE]: Automated Learning Capture System #1397

New issue
New issue
Open
Open
[RFE]: Automated Learning Capture System#1397
@agno01

Description

@agno01
agno01
opened on Feb 2, 2026

RFE: Automated Learning Capture System

RFC ID: RFE-2026-002
Author: Community Consolidation
Date: 2026-02-02
Status: Draft - Community Review
Priority: High
Consolidates: #1077, #598, #1364, #869, #663

Abstract

This RFE proposes an Automated Learning Capture System that bridges the gap between ephemeral session insights and persistent knowledge documentation. The system enables agents to detect, classify, validate, and persist learnings into the appropriate knowledge base files (AGENTS.md, CLAUDE.md, skills) through a GitOps-compliant workflow.

This proposal consolidates 5 open community requests into a unified, principled design aligned with Open Practice Library continuous learning patterns.

Table of Contents

  1. Motivation
  2. Related Work
  3. Design Principles
  4. Technical Specification
  5. Security Considerations
  6. Implementation Plan
  7. Success Metrics
  8. Open Questions
  9. References

1. Motivation

1.1 Problem Statement

Currently, oh-my-opencode has a knowledge capture gap:

┌─────────────────────────────────────────────────────────────────────────┐
│                         CURRENT STATE                                    │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   Session Work ──► .sisyphus/notepads/ ──► [DEAD END]                   │
│        │                                                                 │
│        │           Knowledge stays in notepads                           │
│        │           Never reaches AGENTS.md                               │
│        │           Lost after plan completion                            │
│        │                                                                 │
│        └──► Hard-won insights fade ──► Same mistakes repeated           │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Impact:

  • Knowledge loss: Incident resolutions, anti-patterns, and procedures discovered during work sessions are not persisted
  • Repeated mistakes: Same gotchas rediscovered across sessions because they weren't documented
  • Documentation drift: AGENTS.md becomes stale without continuous updates
  • Onboarding friction: New users/agents don't benefit from accumulated organizational wisdom

1.2 Community Demand

This feature has been requested multiple times:

Issue Title Core Request Date
#1077 Learning System Agent learns from mistakes, writes new skills 2026-01-28
#598 Agents update AGENTS.md Persist anti-patterns before ending task 2026-01-27
#1364 Session Debrief Post-plan learning synthesis from notepads 2026-02-01
#869 Central Memory + Judge Cross-session learning with .sisyphus/memory.json 2026-01-27
#663 Reflexion Learning Intra-loop learning from failures 2026-01-10
#74 Memory System Discussion Community discussion on implementation Ongoing

Closed PR: #1184 Project Mnemosyne - Memory enhancement system (not merged, but shows community interest)

1.3 Existing Infrastructure

The foundation already exists:

Component Location Status
Notepad system .sisyphus/notepads/{plan}/learnings.md ✅ Exists
Session tools session_list, session_read, session_search ✅ Exists
PostToolUse hooks src/hooks/claude-code-hooks/post-tool-use.ts ✅ Exists
Context injection src/features/context-injector/ ✅ Exists
Git workflow git-master skill ✅ Exists
Command system src/features/builtin-commands/ ✅ Exists

Gap: No automation bridge between session learnings and persistent documentation.

2. Related Work

2.1 Industry Patterns

System Approach Learnings for This RFE
SwarmTools Learning Systems Database-backed learning with skill generation Inspiration for #1077
claude-mem Cross-session memory persistence Simple but lacks structure
Reflexion (Shinn et al.) Self-reflection in language agents Inspiration for #663
GitHub Copilot Spaces Context organization with repos, PRs, issues Knowledge proximity principle

2.2 Open Practice Library Alignment

This RFE is designed around Open Practice Library principles:

The Mobius Loop

"The Mobius Loop is a way of thinking about the iterative process of Discovery, Options, and Delivery."
— openpracticelibrary.com/practice/mobius-loop

        ┌─────────────────────────────────────────────────────────┐
        │                    MOBIUS LOOP                           │
        │                                                          │
        │     DISCOVERY ◄──────────────────────► DELIVERY          │
        │         │                                  │             │
        │         │         OPTIONS PIVOT            │             │
        │         │              ▲                   │             │
        │         │              │                   │             │
        │         └──────────────┴───────────────────┘             │
        │                        │                                 │
        │                   LEARNING                               │
        │              (This RFE fills this gap)                   │
        └─────────────────────────────────────────────────────────┘

Alignment: This RFE closes the learning loop by capturing insights from Delivery and feeding them back into Discovery.

4Ls Retrospective

"The 4Ls is a simple but effective retrospective technique... helping the team capture Liked, Learned, Lacked, and Longed For."
— openpracticelibrary.com/practice/4ls-retrospective

4L Category Mapped Learning Type Example
Liked procedure "The TDD RED→GREEN→REFACTOR cycle caught edge cases early"
Learned gotcha, anti-pattern "NEVER use @types/node - use bun-types instead"
Lacked warning "Heavy PreToolUse hooks slow every tool call"
Longed For enhancement "Wish we had automatic hook performance profiling"

Establish Shared Principles

"Establishing shared principles helps teams navigate complex decisions by providing guardrails."
— openpracticelibrary.com/practice/establish-shared-principles

Alignment: Classification rules in this RFE establish guardrails for where learnings belong (AGENTS.md vs CLAUDE.md vs skills).

Blameless Postmortems

"Turn incidents into learning investments rather than blame games."
— openpracticelibrary.com/practice/blameless-postmortem

Alignment: The incident-resolution learning type captures what happened and what fixed it, without assigning blame.

Truth Proximity

"Documentation should be close to the source in time, content, and medium."
— DocOps Principle

Alignment: Tier 1 (in-session capture) captures learnings immediately during work, maximizing truth proximity.

3. Design Principles

3.1 Core Principles

Principle Description Implementation
Capture at Source Learn where work happens PostToolUse hook detection
Human in the Loop Never auto-merge to knowledge base Always create PR for review
Progressive Refinement Raw → Structured → Persisted 3-tier system
GitOps Compliance All changes via PR git-master skill integration
Graceful Degradation System works without automation Manual /capture-learning always available

3.2 Anti-Principles (What We Avoid)

Anti-Principle Why It's Bad How We Avoid
Auto-merge learnings Prompt injection risk, no review PR-only workflow
Capture everything Noise, review fatigue Conservative detection, explicit capture
Complex classification Hard to maintain, confusing Simple 5-type taxonomy
Cross-repo learning Context pollution Per-repo knowledge base

4. Technical Specification

4.1 System Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                        LEARNING CAPTURE ARCHITECTURE                         │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │ TIER 1: In-Session Capture (Immediate)                               │    │
│  │ ────────────────────────────────────────                             │    │
│  │ • /capture-learning command (explicit)                               │    │
│  │ • learning-detector hook (auto-suggest)                              │    │
│  │ • Writes to .sisyphus/learnings/{session}.jsonl                      │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                                    │                                         │
│                                    ▼                                         │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │ TIER 2: Validation Layer (Security Gate)                             │    │
│  │ ────────────────────────────────────────                             │    │
│  │ • Prompt injection detection                                         │    │
│  │ • Sensitive data detection (secrets, credentials)                    │    │
│  │ • Format validation                                                  │    │
│  │ • Deduplication check                                                │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                                    │                                         │
│                                    ▼                                         │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │ TIER 3: Persistence Layer (GitOps)                                   │    │
│  │ ────────────────────────────────────────                             │    │
│  │ • /summarize-learnings → PR draft                                    │    │
│  │ • /mine-sessions → batch PR                                          │    │
│  │ • Human review required before merge                                 │    │
│  │ • Target: AGENTS.md | CLAUDE.md | .opencode/skills/                  │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

4.2 Data Model

Learning Entry Schema

interface LearningEntry {
  // Identity
  id: string                    // UUID
  session_id: string            // Source session
  timestamp: string             // ISO 8601
  
  // Classification
  type: LearningType
  domain: string                // Directory path or "general"
  target: LearningTarget
  
  // Content
  title: string                 // Short summary (< 80 chars)
  context: string               // What you were doing
  learning: string              // The actual insight
  tags: string[]                // Searchable tags
  
  // Lifecycle
  status: LearningStatus
  validation: ValidationResult
  
  // Provenance
  source: {
    tool?: string               // Tool that triggered detection
    error?: string              // Error that was resolved
    plan?: string               // Associated plan name
  }
}

type LearningType = 
  | "incident-resolution"       // Error → Fix → Success
  | "anti-pattern"              // Things to avoid
  | "procedure"                 // Step-by-step how-to
  | "gotcha"                    // Non-obvious behavior
  | "warning"                   // Critical constraints

type LearningTarget =
  | "AGENTS.md"                 // Root knowledge base
  | "CLAUDE.md"                 // Domain-specific (src/*/AGENTS.md)
  | `skill/${string}`           // Skill file (.opencode/skills/*.md)

type LearningStatus =
  | "captured"                  // In session storage
  | "validated"                 // Passed security checks
  | "proposed"                  // In PR draft
  | "merged"                    // In knowledge base
  | "rejected"                  // Failed validation or review

interface ValidationResult {
  passed: boolean
  checks: {
    prompt_injection: boolean
    sensitive_data: boolean
    duplicate: boolean
    format_valid: boolean
  }
  flags: string[]               // Human-readable warnings
}

Storage Format

Session Learnings (.sisyphus/learnings/{session_id}.jsonl):

{"id":"lr_001","type":"gotcha","title":"bun-types required instead of @types/node","learning":"...","timestamp":"2026-02-02T10:30:00Z",...}
{"id":"lr_002","type":"procedure","title":"Background agent concurrency limits","learning":"...","timestamp":"2026-02-02T11:15:00Z",...}

Aggregated Index (.sisyphus/learnings/index.json):

{
  "version": "1.0.0",
  "last_updated": "2026-02-02T12:00:00Z",
  "total_count": 42,
  "by_type": {
    "incident-resolution": 12,
    "anti-pattern": 8,
    "procedure": 15,
    "gotcha": 5,
    "warning": 2
  },
  "by_target": {
    "AGENTS.md": 20,
    "CLAUDE.md": 18,
    "skill/git-master": 4
  }
}

4.3 Commands

/capture-learning

Purpose: Explicit learning capture during work sessions.

Location: src/features/builtin-commands/templates/capture-learning.ts

Usage:

# Basic usage
/capture-learning "NEVER use @types/node - always use bun-types instead"

# With classification
/capture-learning "Empty catch blocks hide errors - always handle or rethrow" --type=anti-pattern

# With explicit target
/capture-learning "Git commits must group test and implementation together" --target=skill/git-master

Arguments:

Argument Required Default Description
<description> Yes - The learning to capture
--type No gotcha One of: incident-resolution, anti-pattern, procedure, gotcha, warning
--domain No Auto-detect from cwd Target domain/directory
--target No Auto-classify One of: AGENTS.md, CLAUDE.md, skill/<name>

Classification Rules:

const CLASSIFICATION_RULES: ClassificationRule[] = [
  // Global concerns → Root AGENTS.md
  { pattern: /security|credentials|secrets|auth/i, target: "AGENTS.md" },
  { pattern: /tdd|testing|test-driven/i, target: "AGENTS.md" },
  { pattern: /type.?safety|typescript|as any|ts-ignore/i, target: "AGENTS.md" },
  
  // Domain-specific → CLAUDE.md
  { pattern: /hooks\/([^/]+)/, target: "src/hooks/$1/AGENTS.md" },
  { pattern: /features\/([^/]+)/, target: "src/features/$1/AGENTS.md" },
  
  // Tool-specific → Skills
  { pattern: /git|commit|rebase|merge/i, target: "skill/git-master" },
  { pattern: /playwright|browser|screenshot/i, target: "skill/playwright" },
  { pattern: /frontend|ui|ux|css|styling/i, target: "skill/frontend-ui-ux" },
]

/summarize-learnings

Purpose: End-of-session learning extraction and PR creation.

Location: src/features/builtin-commands/templates/summarize-learnings.ts

Usage:

# Summarize current session
/summarize-learnings

# Preview without creating PR
/summarize-learnings --dry-run

# Summarize specific session/plan
/summarize-learnings --plan=refactor-hooks-system

Workflow:

1. Read .sisyphus/learnings/{session}.jsonl
2. Validate all entries (security checks)
3. Group by target file
4. Generate diff for each target
5. Create branch: docs/learnings-{plan}-{date}
6. Commit changes with structured message
7. Create PR draft with learning summary
8. Output PR URL for user review

PR Template:

## Learning Capture: {plan_name}

### Summary
- **Session**: {session_id}
- **Duration**: {duration}
- **Learnings Captured**: {count}

### Changes by File

#### AGENTS.md (+{n} learnings)
- [ ] {learning_1_title}
- [ ] {learning_2_title}

#### src/hooks/AGENTS.md (+{n} learnings)
- [ ] {learning_3_title}

### Validation Status
All learnings passed security validation.

### Review Checklist
- [ ] Learnings are accurate and actionable
- [ ] No sensitive information exposed
- [ ] Correct target files selected
- [ ] No duplicate information

/mine-sessions

Purpose: Batch mining of historical sessions for unextracted learnings.

Location: src/features/builtin-commands/templates/mine-sessions.ts

Usage:

# Mine last 30 days
/mine-sessions

# Mine with date range
/mine-sessions --since="2026-01-01" --until="2026-01-31"

# Mine with custom keywords
/mine-sessions --keywords="never,always,critical,workaround,fixed"

# Preview only
/mine-sessions --dry-run

Mining Heuristics:

const MINING_PATTERNS = [
  // Explicit learning markers
  { pattern: /learned|discovered|realized|found out/i, weight: 1.0 },
  
  // Anti-pattern indicators
  { pattern: /never|always|critical|important|warning/i, weight: 0.8 },
  
  // Resolution patterns
  { pattern: /fixed by|solved by|workaround|the issue was/i, weight: 0.9 },
  
  // Procedure patterns
  { pattern: /steps?:|procedure:|how to:|to do this/i, weight: 0.7 },
  
  // Error recovery (tool failure → success sequence)
  { pattern: /error.*then.*success|failed.*retry.*worked/i, weight: 0.95 },
]

/recall-learnings

Purpose: Query and inject relevant learnings into current context.

Location: src/features/builtin-commands/templates/recall-learnings.ts

Usage:

# Search learnings
/recall-learnings "background agent concurrency"

# Filter by type
/recall-learnings --type=anti-pattern

# Filter by domain
/recall-learnings --domain=src/hooks

4.4 Learning Detection Hook

Purpose: Automatic learning detection during work.

Location: src/hooks/learning-detector/index.ts

Hook Type: PostToolUse

Behavior: Suggests (does not auto-capture) learnings when patterns detected.

// src/hooks/learning-detector/index.ts
import { createHook, PostToolUseHook } from '../claude-code-hooks'
import { detectLearningSignals, LearningSignal } from './heuristics'

export function createLearningDetectorHook(): PostToolUseHook {
  return createHook({
    name: 'learning-detector',
    event: 'post_tool_use',
    
    handler: async (context, toolResult) => {
      // Skip if disabled
      if (!context.config.learning_capture?.auto_detect) {
        return {}
      }
      
      const signals = detectLearningSignals(context, toolResult)
      
      if (signals.length === 0) {
        return {}
      }
      
      // Inject suggestion (NOT automatic capture)
      const suggestion = formatSuggestion(signals[0])
      
      return {
        inject: {
          type: 'system',
          content: suggestion
        }
      }
    }
  })
}

function formatSuggestion(signal: LearningSignal): string {
  return `[LEARNING DETECTED] ${signal.summary}

Consider capturing this insight:
\`/capture-learning "${signal.summary}" --type=${signal.type}\`

This is a suggestion only. Use the command above to persist this learning.`
}

Detection Heuristics:

// src/hooks/learning-detector/heuristics.ts

export interface LearningSignal {
  type: LearningType
  summary: string
  confidence: number
  source: 'error_recovery' | 'keyword' | 'pattern'
}

export function detectLearningSignals(
  context: HookContext,
  toolResult: ToolResult
): LearningSignal[] {
  const signals: LearningSignal[] = []
  
  // Pattern 1: Error recovery (high confidence)
  if (context.previousToolFailed && toolResult.success) {
    signals.push({
      type: 'incident-resolution',
      summary: `Fixed: ${truncate(context.previousError, 60)} → ${truncate(toolResult.summary, 40)}`,
      confidence: 0.9,
      source: 'error_recovery'
    })
  }
  
  // Pattern 2: Anti-pattern keywords in assistant response
  const antiPatternMatch = context.lastAssistantMessage?.match(
    /\b(NEVER|ALWAYS|CRITICAL|IMPORTANT|WARNING)[:\s]+([^.]+\.)/gi
  )
  if (antiPatternMatch) {
    signals.push({
      type: 'anti-pattern',
      summary: cleanKeywordMatch(antiPatternMatch[0]),
      confidence: 0.7,
      source: 'keyword'
    })
  }
  
  // Pattern 3: Procedure documentation
  const procedureMatch = context.lastAssistantMessage?.match(
    /(?:steps?|procedure|how to)[:\s]+\n((?:\d+\.|[-*])[^\n]+\n?){2,}/gi
  )
  if (procedureMatch) {
    signals.push({
      type: 'procedure',
      summary: extractProcedureTitle(procedureMatch[0]),
      confidence: 0.6,
      source: 'pattern'
    })
  }
  
  // Sort by confidence, return top signals
  return signals
    .filter(s => s.confidence >= 0.6)
    .sort((a, b) => b.confidence - a.confidence)
    .slice(0, 2)
}

4.5 Configuration Schema

Add to src/config/schema.ts:

const learningCaptureSchema = z.object({
  // Master enable/disable
  enabled: z.boolean().default(true),
  
  // Auto-detection hook
  auto_detect: z.boolean().default(false),  // Opt-in initially
  
  // Detection sensitivity
  detection_confidence_threshold: z.number().min(0).max(1).default(0.7),
  
  // Keywords that boost detection confidence
  detection_keywords: z.array(z.string()).default([
    'never', 'always', 'critical', 'gotcha', 
    'learned', 'workaround', 'fixed', 'warning'
  ]),
  
  // Classification rules override
  classification_rules: z.record(z.string(), z.string()).optional(),
  
  // Default target for unclassified learnings
  default_target: z.enum(['AGENTS.md', 'CLAUDE.md']).default('AGENTS.md'),
  
  // Security settings
  security: z.object({
    // Block learnings containing these patterns
    blocked_patterns: z.array(z.string()).default([
      'password', 'secret', 'api_key', 'token', 'credential'
    ]),
    // Require validation before any persistence
    require_validation: z.boolean().default(true),
  }).default({}),
  
  // GitOps settings
  gitops: z.object({
    // Branch prefix for learning PRs
    branch_prefix: z.string().default('docs/learnings'),
    // Auto-create PR after N captured learnings
    auto_pr_threshold: z.number().optional(),
    // PR reviewers
    reviewers: z.array(z.string()).optional(),
  }).default({}),
})

Example Configuration (.opencode/oh-my-opencode.json):

{
  "learning_capture": {
    "enabled": true,
    "auto_detect": true,
    "detection_confidence_threshold": 0.7,
    "detection_keywords": ["never", "always", "critical", "gotcha"],
    
    "classification_rules": {
      "typescript": "AGENTS.md",
      "src/hooks": "src/hooks/AGENTS.md",
      "src/features": "src/features/AGENTS.md"
    },
    
    "security": {
      "blocked_patterns": ["password", "secret", "api_key", "token"],
      "require_validation": true
    },
    
    "gitops": {
      "branch_prefix": "docs/learnings",
      "auto_pr_threshold": 5,
      "reviewers": ["@maintainers"]
    }
  }
}

5. Security Considerations

5.1 Threat Model

Threat Impact Mitigation
Prompt Injection Malicious instructions in AGENTS.md Validation layer + human review
Sensitive Data Exposure Credentials in learnings Blocked pattern detection
Knowledge Poisoning Incorrect learnings degrade quality PR review required
Denial of Service Excessive learning capture Rate limiting, thresholds

5.2 Validation Layer

// src/features/learning-capture/validator.ts

export interface ValidationResult {
  passed: boolean
  checks: {
    prompt_injection: boolean
    sensitive_data: boolean
    duplicate: boolean
    format_valid: boolean
  }
  flags: string[]
}

export function validateLearning(
  entry: LearningEntry,
  config: LearningCaptureConfig
): ValidationResult {
  const flags: string[] = []
  
  // Check 1: Prompt injection patterns
  const injectionPatterns = [
    /ignore previous instructions/i,
    /system:\s*you are/i,
    /<\/?(?:system|user|assistant)>/i,
    /\{\{.*\}\}/,  // Template injection
    /```\s*(?:system|prompt)/i,
  ]
  
  const hasInjection = injectionPatterns.some(p => 
    p.test(entry.learning) || p.test(entry.context)
  )
  if (hasInjection) {
    flags.push('BLOCKED: Potential prompt injection detected')
  }
  
  // Check 2: Sensitive data patterns
  const sensitivePatterns = config.security.blocked_patterns.map(
    p => new RegExp(p, 'i')
  )
  
  const hasSensitive = sensitivePatterns.some(p =>
    p.test(entry.learning) || p.test(entry.context)
  )
  if (hasSensitive) {
    flags.push('BLOCKED: Potential sensitive data detected')
  }
  
  // Check 3: Duplicate detection (fuzzy match against existing)
  const isDuplicate = await checkDuplicate(entry)
  if (isDuplicate) {
    flags.push('WARNING: Similar learning already exists')
  }
  
  // Check 4: Format validation
  const isValidFormat = 
    entry.title.length > 0 && entry.title.length <= 80 &&
    entry.learning.length > 0 && entry.learning.length <= 2000
  if (!isValidFormat) {
    flags.push('BLOCKED: Invalid format (check title/learning length)')
  }
  
  return {
    passed: !hasInjection && !hasSensitive && isValidFormat,
    checks: {
      prompt_injection: !hasInjection,
      sensitive_data: !hasSensitive,
      duplicate: !isDuplicate,
      format_valid: isValidFormat,
    },
    flags,
  }
}

5.3 Defense in Depth

┌─────────────────────────────────────────────────────────────────────┐
│                    SECURITY LAYERS                                   │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│   Layer 1: Detection Filter                                          │
│   └── Conservative heuristics (high confidence threshold)            │
│                                                                      │
│   Layer 2: Capture Validation                                        │
│   └── Prompt injection detection                                     │
│   └── Sensitive data detection                                       │
│   └── Format validation                                              │
│                                                                      │
│   Layer 3: Storage Isolation                                         │
│   └── Learnings stored in .sisyphus/ (not injected directly)         │
│   └── Separate from runtime context                                  │
│                                                                      │
│   Layer 4: GitOps Gate                                               │
│   └── All changes via PR (never direct merge)                        │
│   └── Human review required                                          │
│   └── CI checks on PR                                                │
│                                                                      │
│   Layer 5: Runtime Isolation                                         │
│   └── Learnings injected as read-only context                        │
│   └── Cannot modify agent instructions                               │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

6. Implementation Plan

6.1 Phased Rollout

Phase Scope Issues Addressed Effort Risk
0 Create umbrella issue, consolidate discussion All 2h None
1 /capture-learning command #598 6h Low
2 Validation layer Security 4h Low
3 /summarize-learnings with PR #598, #1364 10h Medium
4 /recall-learnings query #869 4h Low
5 Learning detection hook #1077 8h Medium
6 /mine-sessions batch #663 8h Medium
7 Metrics collection #869 6h Low

Total Estimated Effort: ~48 hours (2-3 weeks part-time)

6.2 File Structure

src/
├── features/
│   └── learning-capture/
│       ├── index.ts              # Main exports
│       ├── types.ts              # LearningEntry, ValidationResult
│       ├── storage.ts            # Read/write .sisyphus/learnings/
│       ├── validator.ts          # Security validation
│       ├── classifier.ts         # Target classification
│       ├── deduplicator.ts       # Fuzzy duplicate detection
│       ├── miner.ts              # Session mining logic
│       └── index.test.ts         # Unit tests
│
├── hooks/
│   └── learning-detector/
│       ├── index.ts              # PostToolUse hook
│       ├── heuristics.ts         # Detection patterns
│       └── index.test.ts         # Unit tests
│
└── features/builtin-commands/templates/
    ├── capture-learning.ts       # /capture-learning
    ├── summarize-learnings.ts    # /summarize-learnings
    ├── mine-sessions.ts          # /mine-sessions
    └── recall-learnings.ts       # /recall-learnings

6.3 Testing Strategy

Test Type Coverage Location
Unit Validator, classifier, deduplicator *.test.ts
Integration Command → Storage → PR e2e/learning-capture.test.ts
Security Injection attempts, sensitive data security/learning-capture.test.ts

TDD Requirement: All code must follow RED → GREEN → REFACTOR cycle per project conventions.

7. Success Metrics

7.1 Quantitative Metrics

Metric Target Measurement Method
Learning capture rate 80%+ of significant learnings Compare session content vs captured
Documentation freshness <7 days from learning to merge Git commit timestamps
Deduplication accuracy <5% false positives Manual review sample
Validation accuracy <1% false negatives (security) Adversarial testing
User adoption 50%+ sessions use capture Command usage telemetry

7.2 Qualitative Metrics

Metric Target Measurement Method
Knowledge reuse Learnings referenced in future sessions /recall-learnings usage
Mistake reduction Same gotchas not rediscovered Session analysis
Onboarding improvement New users find documented solutions User feedback

8. Open Questions

8.1 Resolved

Question Decision Rationale
Auto-detect opt-in or opt-out? Opt-in Conservative start, avoid noise
Auto-merge without PR? Never GitOps discipline, security
Multi-repo learning sharing? No Context pollution risk

8.2 For Community Discussion

Question Options Recommendation
Should detection hook show toast notification? A) Toast + inject, B) Inject only, C) Toast only B) Inject only (less disruptive)
Maximum learnings per session before auto-PR? A) 3, B) 5, C) 10, D) No limit B) 5 (balance between noise and capture)
Should /mine-sessions require confirmation per learning? A) Yes, B) No (batch review), C) Configurable C) Configurable (default: batch)
Integration with Momus for learning review? A) Yes (expensive), B) No, C) Optional C) Optional (for high-stakes repos)

9. References

9.1 Open Practice Library

9.2 Academic

9.3 Industry

9.4 Related Issues

Appendix A: Example Workflow

┌─────────────────────────────────────────────────────────────────────────────┐
│ EXAMPLE: Developer debugging TypeScript type errors in hook system           │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│ 1. Developer encounters error:                                               │
│    "Type 'unknown' is not assignable to type 'HookContext'"                  │
│                                                                              │
│ 2. After investigation, discovers solution:                                  │
│    "Must use proper type guards instead of 'as any' assertions"              │
│                                                                              │
│ 3. Learning detector (PostToolUse) notices error → success pattern:          │
│    [LEARNING DETECTED] Fixed: Type assertion error →                         │
│    use type guard with runtime check                                         │
│                                                                              │
│ 4. Developer captures explicitly:                                            │
│    /capture-learning "NEVER use 'as any' - create proper type guards"        │
│                 --type=anti-pattern                                          │
│                                                                              │
│ 5. At session end:                                                           │
│    /summarize-learnings                                                      │
│    → Creates PR: "docs: Add learnings from issue #1234"                      │
│    → Targets: AGENTS.md (Type Safety section)                                │
│                                                                              │
│ 6. Team reviews PR, merges                                                   │
│                                                                              │
│ 7. Future sessions: Agent reads AGENTS.md, uses type guards                  │
│    instead of unsafe type assertions                                         │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Appendix B: Migration from Existing Systems

For users with existing .sisyphus/notepads/*/learnings.md files:

# One-time migration command
/mine-sessions --source=notepads --migrate

# This will:
# 1. Parse existing learnings.md files
# 2. Convert to structured format
# 3. Validate and deduplicate
# 4. Create comprehensive PR with all historical learnings

Feedback Welcome: Please comment on this RFE with:

  1. Use cases we missed
  2. Security concerns
  3. Implementation preferences
  4. Priority of phases

To support this RFE: React with 👍 and comment with your use case.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions