Knowledge Extractor

Knowledge Extractor Skill

Purpose

This skill automatically extracts, synthesizes, and preserves knowledge from conversations, debugging sessions, failed attempts, and solved problems. It converts ephemeral interactions into persistent organizational knowledge that improves future performance.

When to Use This Skill

• Session End Analysis: Extract learnings before session context is lost
• After Complex Debugging: Capture root causes and solutions while fresh
• Following Failed Attempts: Document what didn't work and why
• Successful Problem Solving: Preserve solutions for future reuse
• New Pattern Discovery: Identify patterns that should be documented
• Repeated Workflows: Recognize when to create new specialized agents
• Cross-Session Learning: Build organizational memory from individual sessions

Core Philosophy: Knowledge Preservation

Session Context: Ephemeral conversation context that will be lost without active preservation Persistent Knowledge: Structured learnings that improve future performance Pattern Recognition: Identifying when solutions are repeated and should be automated Organizational Growth: Converting individual learning into system-wide improvement

Knowledge Extraction Framework

Three Types of Knowledge Extraction

1. Discoveries - Novel Insights and Root Causes

What it captures: Problems encountered, root causes identified, solutions implemented

When to extract:

• After solving a complex bug
• When debugging reveals unexpected behavior
• When discovering wrong assumptions
• After identifying missing functionality
• When learning why something failed

Format for DISCOVERIES.md:

## [Brief Title] (YYYY-MM-DD)

### Issue

What problem or challenge was encountered?

### Root Cause

Why did this happen? What was the underlying issue?

### Solution

How was it resolved? Include code examples if relevant.

### Key Learnings

What insights were gained? What should be remembered?

### Prevention

How can this be avoided in the future?

Quality Criteria:

• ✅ Specific problem, not generic advice
• ✅ Root cause clearly identified
• ✅ Working solution included
• ✅ Learning generalized for reuse
• ✅ Prevention strategy documented

2. Patterns - Reusable Solutions

What it captures: Proven solutions to recurring problems, architectural approaches, design patterns

When to extract:

• After solving a problem similar to known patterns
• When recognizing a repeated problem type
• When implementing a proven solution
• When discovering a best practice that works
• When solution applies across multiple contexts

Format for PATTERNS.md:

## Pattern: [Name]

### Challenge

What problem does this pattern solve?

### Solution

How does the pattern work? Include code/examples.

### Key Points

- Main insight 1
- Main insight 2
- When to use / when not to use

### When to Use

Specific scenarios where this pattern applies.

### Real Impact

Where has this pattern been used successfully?

### Related Patterns

Links to similar or complementary patterns.

Quality Criteria:

• ✅ General enough to apply to multiple situations
• ✅ Problem clearly defined
• ✅ Solution has proven track record
• ✅ Working code examples
• ✅ Clear when/when-not-to-use guidance

3. Agent Creation - Automation of Repeated Workflows

What it captures: Workflows that are repeated frequently, specialized expertise areas, complex multi-step processes

When to extract:

• After performing the same workflow 2-3 times
• When recognizing a specialized skill area
• When workflow has clear inputs/outputs
• When automating would save significant time
• When problem domain is narrow and well-defined

Agent Creation Trigger Checklist:

• [ ] Same workflow repeated 2+ times
• [ ] Workflow takes 30+ minutes to execute
• [ ] Workflow has clear specialized focus
• [ ] Workflow can be automated with current tools
• [ ] Problem domain is narrow and well-defined
• [ ] Would be high-value to automate

Example Agent Creation:

## Recommended New Agent: [domain]-[specialty]

### Problem

What repeated workflow would this agent handle?

### Scope

What's in scope | What's explicitly out of scope

### Inputs

What information does the agent need?

### Process

Step-by-step workflow the agent follows

### Outputs

What does the agent produce?

### Value

How much time/effort does this save?

### Integration

Where in the workflow does this fit?

Step-by-Step Extraction Process

Step 1: Session Analysis (5 minutes)

Review entire conversation/session:

1. What was the original problem/request?
2. What approaches were tried?
3. Which attempts failed and why?
4. What succeeded and why?
5. What was learned in the process?
6. What surprised you?
7. What took longer than expected?
8. What would have helped?

Step 2: Pattern Recognition (5 minutes)

Identify patterns in the work:

1. Have I seen this problem before? (→ DISCOVERIES)
2. Is this a generalizable solution? (→ PATTERNS)
3. Would this be worth automating? (→ AGENT)
4. What was the root cause? (Why, not just what)
5. What should others know about this?
6. What should be remembered to avoid repetition?

Step 3: Knowledge Extraction (10 minutes)

Extract and structure knowledge:

For DISCOVERIES.md:

• Specific issue encountered
• Root cause analysis
• Solution implemented
• Key learnings generalized
• Prevention strategy

For PATTERNS.md:

• Problem the pattern solves
• How the pattern works
• When to use / when not to use
• Working code examples
• Related patterns

For New Agent:

• Repeated workflow identified
• Clear scope and boundaries
• Input/output requirements
• Step-by-step process
• Expected value/time savings

Step 4: Integration (3 minutes)

Place knowledge in correct locations:

Memory → Store discovery using store_discovery() from amplihack.memory.discoveries
PATTERNS.md → New pattern in appropriate section
Agent → Create in .claude/agents/amplihack/specialized/

Step 5: Validation (2 minutes)

Ensure quality:

[ ] Entry is specific, not generic
[ ] Entry follows template format
[ ] Examples/code provided
[ ] Quality sufficient for reuse
[ ] Grammar and clarity checked
[ ] Related items cross-referenced

Usage Examples

Example 1: Extract Discovery After Bug Fix

Scenario: Just spent 45 minutes debugging why pre-commit hooks weren't working

User: Extract what we learned from debugging the pre-commit issue.

Claude:
1. Analyzes conversation showing:
   - Initial problem: hooks appeared to run but didn't modify files
   - False leads: blamed merge conflicts, tool versions
   - Root cause found: Hooks couldn't write to files due to cloud sync lock
   - Solution: Added exponential backoff retry logic
   - Time to discover: 45 minutes

2. Creates DISCOVERIES.md entry:
   - Issue: Pre-commit hooks silently failing
   - Root Cause: Cloud sync (OneDrive) file locks
   - Solution: Exponential backoff retry (0.1s, 0.2s, 0.4s...)
   - Key Learning: Cloud sync issues silent - need defensive coding
   - Prevention: Add retry logic for file I/O, test with cloud storage

3. Offers to also:
   - Add pattern for "Resilient File I/O" to PATTERNS.md
   - Suggest new agent for cloud-sync issue detection

Example 2: Extract Pattern from Successful Implementation

Scenario: Just finished implementing module regeneration strategy

User: Extract the pattern we discovered for building regeneratable modules.

Claude:
1. Analyzes implementation showing:
   - Clear __all__ exports defining public interface
   - Self-contained module structure
   - Type-hinted functions with docstrings
   - Comprehensive test coverage
   - Working examples

2. Creates PATTERNS.md entry:
   - Pattern: Module Regeneration Structure
   - Challenge: Modules become tightly coupled, hard to regenerate
   - Solution: Brick & studs design with __all__ public API
   - Key Points: Clear contracts, single responsibility, testable behavior
   - When to Use: Any utility module, anything that might be regenerated
   - Real Impact: Enables AI to rebuild modules without breaking system

3. Cross-references:
   - Relates to "Bricks & Studs Module Design"
   - Enables "Builder Agent Workflow"

Example 3: Identify New Agent Creation Opportunity

Scenario: Just debugged CI failure using 5-step diagnostic process for 3rd time

User: We keep using the same CI debugging process. Should we automate it?

Claude:
1. Analyzes past sessions:
   - Session 1: 45 minutes CI debugging (version mismatch issue)
   - Session 2: 30 minutes CI debugging (pre-commit hook issue)
   - Session 3: 25 minutes CI debugging (merge conflict issue)
   - Pattern: Same 5-step process each time

2. Recommends new agent:
   - Name: ci-diagnostic-workflow
   - Problem: Each CI failure requires manual diagnosis, takes 30-45 min
   - Scope: Diagnoses CI failures, suggests fixes (doesn't auto-fix)
   - Process:
     1. Check environment (Python version, tool versions)
     2. Analyze CI logs for error patterns
     3. Detect common issues (conflicts, missing deps)
     4. Suggest solutions
     5. Coordinate parallel diagnostic agents
   - Value: Reduce diagnosis time from 45 min → 15 min

3. Proposes creating:
   - .claude/agents/amplihack/ci-diagnostic-workflow.md
   - Can delegate to: fix-agent for implementation

Example 4: Multi-Level Extraction

Scenario: Complex architectural decision with multiple learnings

User: Extract everything we learned from deciding on the memory architecture.

Claude:
1. Session involved:
   - 2 failed approaches (too complex, wrong threat model)
   - 1 successful approach (simple, fits threat model)
   - Discovery of meta-pattern for architecture decisions

2. Creates THREE extractions:

   DISCOVERIES.md:
   - Issue: Pattern Applicability Analysis
   - Root Cause: Importing patterns without validating threat match
   - Solution: Five-phase applicability analysis framework
   - Learning: Threat model match is critical first check

   PATTERNS.md:
   - New Pattern: Threat Model Precision Principle
   - Challenge: Fault tolerance mechanisms mismatch problem space
   - Solution: Validate threat model before adopting patterns
   - When: Before adopting any "best practice" from different domain

   Recommended Agent:
   - Name: pattern-applicability-analyzer
   - Automate: Quick assessment of pattern applicability
   - Value: Prevent adopting wrong patterns early

Knowledge Quality Checklist

Before finalizing an extraction, verify:

For DISCOVERIES.md

• [ ] Issue is specific, not generic ("Pre-commit hooks failing" not "Tools broken")
• [ ] Root cause is identified (Why, not just what)
• [ ] Solution is working/proven
• [ ] Learning is generalized (applies beyond this specific case)
• [ ] Prevention strategy is actionable
• [ ] No speculation or future-proofing
• [ ] Code examples provided where relevant

For PATTERNS.md

• [ ] Problem is clear and recognizable
• [ ] Solution has proven track record (used 2+ times successfully)
• [ ] When/when-not-to-use guidance is clear
• [ ] Pattern is general enough for reuse
• [ ] Code examples are working and clear
• [ ] Related patterns are cross-referenced
• [ ] Real impact or usage is documented

For New Agent

• [ ] Workflow has been repeated 2+ times
• [ ] Would save 30+ minutes per execution
• [ ] Problem domain is narrow and well-defined
• [ ] Inputs and outputs are clear
• [ ] Step-by-step process documented
• [ ] High-value worth the automation effort
• [ ] Clear where it fits in workflow

Integration with System

Discovery Memory Lifecycle

1. Extraction: Stored in memory via store_discovery() during session 2. Visibility: Retrieved by get_recent_discoveries() at session start 3. Action: Agents can query memory when solving similar problems 4. Prevention: Prevents repeating same mistakes across sessions 5. Evolution: Updated when better solution found

PATTERNS.md Lifecycle

1. Extraction: Added to PATTERNS.md when pattern proven 2. Catalog: Becomes part of available patterns library 3. Usage: Referenced in relevant agent instructions 4. Teaching: Used in documentation and onboarding 5. Refinement: Improved as more usage data collected

Agent Creation Lifecycle

1. Recommendation: Identified as valuable automation candidate 2. Proposal: Presented to system with expected value 3. Creation: New agent created with clear scope/boundaries 4. Integration: Added to delegation triggers in CLAUDE.md 5. Usage: Available for orchestration across workflows

Real-World Impact Examples

Impact 1: Prevent Wasted Debugging Time

Without knowledge extraction: Repeat same 45-minute debugging process With extraction: Retrieve from memory, fix in 10 minutes

Impact 2: Faster Solution Discovery

Without extraction: Rediscover solutions from scratch With extraction: Reference PATTERNS.md, apply known solution

Impact 3: Automated Workflows

Without extraction: Manual CI debugging every time (30-45 min) With new agent: Automated diagnosis in 5-10 minutes

Common Extraction Mistakes to Avoid

Mistake 1: Too Generic

BAD: "Learned that good error handling is important"
GOOD: "Discovered cloud sync issues cause silent file I/O failures - need exponential backoff retry"

Mistake 2: Missing Root Cause

BAD: "CI failed, fixed it"
GOOD: "CI failed because version mismatch (local 3.12 vs CI 3.11) - fixed by updating pyproject.toml version constraint"

Mistake 3: No Actionable Learning

BAD: "This was complicated"
GOOD: "Multi-layer sanitization at every data transformation prevents credential leakage"

Mistake 4: Over-Generalizing Pattern

BAD: "Always use caching everywhere"
GOOD: "Use smart caching with lifecycle management for expensive operations where results may become stale"

Mistake 5: Agent Creation Without ROI

BAD: "Create agent for task that happens once per quarter"
GOOD: "Create agent for CI debugging workflow that happens 2-3x per week and takes 30-45 minutes"

Extraction Prompts

Use these prompts to trigger knowledge extraction:

Extract Discoveries

Extract what we discovered/learned from this session.
Focus on: root causes, unexpected behaviors, solutions that worked.
Update DISCOVERIES.md appropriately.

Extract Patterns

What patterns should we capture for future reuse?
These should be proven solutions that apply to multiple situations.
Update PATTERNS.md appropriately.

Identify Agent Opportunities

Should we create a new agent to automate any repeated workflows?
Check if any workflow has been done 2+ times and takes 30+ minutes.
Recommend creation with scope and value calculation.

Full Extraction

Perform complete knowledge extraction on this session.
Extract: discoveries, patterns, and agent creation recommendations.
Verify quality and update all three knowledge bases.

Integration Points

With Document-Driven Development

• Use knowledge extraction to update specs and documentation
• Extract patterns to guide next implementation

With Agent Delegation

• Extract when delegating reveals new specializations needed
• Create agents based on repeated delegation patterns

With Pre-Commit Analysis

• Extract discoveries about CI/CD and testing patterns
• Update PATTERNS.md with new approaches discovered

With Session Reflection

• Automatic knowledge extraction at session end
• Preserve learnings before context compaction

Success Metrics

Track effectiveness of knowledge extraction:

• Discoveries Reused: How often DISCOVERIES.md prevents mistakes (target: 80%+)
• Patterns Applied: How often PATTERNS.md enables faster solutions (target: 70%+)
• Agent Usage: How often extracted agents used vs manual approaches (target: 60%+)
• Time Saved: Cumulative time saved by reusing knowledge (target: hours/week)
• Repeated Mistakes: Reduction in making same mistake twice (target: 95%+)

Future Evolution

This skill should grow based on:

• What types of knowledge are most valuable to extract?
• What prevents good extraction?
• How can we make extractions more actionable?
• What knowledge sources are underutilized?
• How can we better surface relevant knowledge?

Document learnings in ~/.amplihack/.claude/context/DISCOVERIES.md.

Knowledge Extraction Example: Agent Creation

Scenario

After diagnosing CI failures for the 3rd time using the same 5-step workflow, each taking 30-45 minutes. Recognition that this should be automated as a specialized agent.

Session Summary

• Session 1: CI version mismatch issue - 45 minutes debug
• Session 2: Pre-commit hook failure - 30 minutes debug
• Session 3: Merge conflict - 25 minutes debug
• Pattern recognized: Same 5-step diagnostic process each time
• Opportunity: Automate diagnostic workflow into new agent

Extraction Process

Step 1: Identify Repeated Workflow

Session 1 workflow:

1. Check CI logs for error patterns (5 min) 2. Verify environment (Python version, tools) (5 min) 3. Compare local vs CI setup (10 min) 4. Identify root cause pattern (15 min) 5. Suggest/implement fix (10 min)

Session 2 workflow:

1. Check logs for errors (5 min) 2. Verify environment (5 min) 3. Check merge conflicts (7 min) 4. Identify root cause (10 min) 5. Suggest fixes (3 min)

Session 3 workflow:

1. Check logs (4 min) 2. Verify environment (5 min) 3. Check for conflicts (6 min) 4. Identify issue (5 min) 5. Suggest fixes (5 min)

Recognition: Same 5-step process, different root causes

Step 2: Validate ROI

Frequency: 2-3 CI failures per week = 8-12 per month Time per session: 25-45 minutes (average 35 minutes) Annual time: 35 min × 10 sessions = 350 minutes = 5.8 hours

If automated:

• Phase 1 (Basic checks): 2 min (vs 10 min)
• Phase 2 (Parallel diagnosis): 8 min (vs 20 min)
• Phase 3 (Synthesis): 5 min (vs 5 min)
• Total: 15 min (vs 35 min) = 57% time reduction

Annual savings: 35 min × 0.43 = 15 min per session × 10 = 150 min = 2.5 hours

ROI: ~1 hour agent development → 2.5 hours saved/year → 2.5:1 ROI in first year

Step 3: Create Agent Recommendation

````markdown

Recommended Agent: ci-diagnostic-workflow

Problem

CI failures are diagnosed manually using same 5-step process every time. Each diagnosis takes 25-45 minutes (average 35 minutes). We encounter 2-3 CI failures per week, representing ~3 hours per month of manual diagnosis.

Scope

In Scope:

• Analyze CI logs for error patterns
• Check environment (Python version, tool versions)
• Detect common issues (merge conflicts, version mismatches, pre-commit hooks)
• Identify root cause
• Suggest fixes (does NOT auto-fix, only suggests)
• Coordinate parallel diagnostic agents for complex issues

Out of Scope:

• Auto-fixing issues (too risky without review)
• Merging branches or resolving conflicts
• Changing CI configuration
• Running tests or builds

Inputs

{
    "pr_number": str,              # GitHub PR number
    "failure_logs": str,           # Complete CI log output
    "branch_info": dict,           # Branch status, merge conflicts
    "environment_info": dict,      # Python version, tool versions
}

````

Process

Phase 1: Environment Quick Check (2 minutes)

1. Parse Python version from CI environment 2. Check tool versions (ruff, pytest, etc.) 3. Detect obvious mismatches with local setup 4. Flag if environment is clearly incorrect

Phase 2: Parallel Diagnostic Analysis (8 minutes) Deploy specialized agents in parallel:

• Log Parser: Extract error signatures from CI logs
• Pattern Matcher: Compare against known failure patterns
• Conflict Detector: Identify merge conflicts
• Version Analyzer: Check for version mismatches

Phase 3: Synthesis and Recommendation (5 minutes)

1. Combine findings from all analyzers 2. Identify primary root cause 3. Rank alternative explanations 4. Suggest fix strategy with confidence score 5. Provide next steps

Outputs

{
    "root_cause": {
        "primary": str,            # Main issue identified
        "alternatives": [str],     # Alternative explanations
        "confidence": float,       # 0.0-1.0 confidence in diagnosis
    },
    "fix_strategy": {
        "steps": [str],            # Ordered fix steps
        "estimated_time": int,     # Minutes to fix
        "risk_level": str,         # low/medium/high
    },
    "escalation_needed": bool,     # True if needs human review
    "related_patterns": [str],     # Known issues this matches
}

Workflow Integration

This agent fits after CI check failure:

Workflow Step 7: CI Check
  ├─ If passes: Continue
  └─ If fails:
      └─ Delegate to ci-diagnostic-workflow
         └─ Returns diagnosis + suggestions
         └─ Developer reviews and implements fixes
         └─ Re-run CI check

Value Calculation

Time Savings Per Issue:

• Manual diagnosis: 35 minutes
• With agent: 15 minutes (setup + review)
• Savings: 20 minutes per issue = 57% reduction

Annual Impact:

• Issues per year: 10-12 (2-3 per week)
• Time saved: 20 min × 12 = 240 minutes = 4 hours
• ROI: ~1 hour development → 4 hours saved = 4:1 ratio

Secondary Benefits:

• Faster time-to-fix (quicker PR merging)
• Fewer repeated CI failures (learning from patterns)
• Better documentation of common issues
• Training resource for new team members

Implementation Strategy

Agent implementation:

1. Create ~/.amplihack/.claude/agents/amplihack/ci-diagnostic-workflow.md 2. Leverage existing agents:

• fix-agent (for automated fixes)
• analyzer (for log analysis)
• patterns (for failure recognition)

3. Coordinate through orchestrator 4. Provide clear output for human decision-making

Quality Metrics

Track effectiveness:

• Average diagnosis time (target: <20 min)
• Root cause accuracy (target: >90%)
• Developer satisfaction (target: >8/10)
• Escalation rate (target: <10%)
• Pattern match hit rate (target: >70%)

Success Criteria

Agent is successful when:

• [ ] Reduces diagnosis time by 50%+ (35 min → <18 min)
• [ ] Root cause identified correctly 90%+ of time
• [ ] Used for 80%+ of CI failures
• [ ] Developer feedback is positive
• [ ] Saves 3+ hours per month

Related Knowledge

Patterns Used:

• CI Failure Rapid Diagnosis (from PATTERNS.md)
• Parallel Agent Deployment (from PATTERNS.md)
• Specialized Agent Creation (from PATTERNS.md)

Integration Points:

• DEFAULT_WORKFLOW.md: Step 7 (CI Check)
• CLAUDE.md: Agent delegation triggers
• DISCOVERIES.md: CI failure patterns

### Step 4: Validation Checklist

- ✅ Workflow repeated 3+ times (not just once)
- ✅ Takes 30+ minutes per execution (35 min average)
- ✅ Problem domain is narrow (CI diagnostics)
- ✅ Well-defined inputs and outputs
- ✅ Clear process steps
- ✅ ROI calculation justifies automation (4:1)
- ✅ Integration point identified (Step 7)
- ✅ Success metrics defined

## Implementation Path

### Step 1: Agent Creation
- Create `~/.amplihack/.claude/agents/amplihack/ci-diagnostic-workflow.md`
- Define clear role and responsibilities
- Specify integration with parallel agent deployment

### Step 2: Integration
- Add to CLAUDE.md agent delegation triggers
- Document in workflow at Step 7
- Test with historical CI failures

### Step 3: Validation
- Run against 5+ historical failures
- Verify root cause identification
- Measure time savings
- Collect feedback

### Step 4: Deployment
- Enable in workflow
- Monitor effectiveness metrics
- Refine based on usage

## Long-Term Value

**Immediate** (first month):
- Reduce CI diagnosis from 35 min → 15 min
- Save ~1 hour per month

**Short-term** (3 months):
- Build pattern database (10+ CI failures)
- Hit rate improves with experience
- Save ~3 hours per month

**Long-term** (1 year):
- Comprehensive CI failure pattern library
- Near-automatic diagnosis for known patterns
- Save ~4 hours per month

## Key Principle

When you recognize a workflow repeated 2-3 times taking 30+ minutes, automation becomes valuable. Extract the workflow as an agent to transform manual work into orchestrated intelligence.

Knowledge Extraction Example: Discovery

Scenario

After a 45-minute debugging session to fix pre-commit hooks failing silently.

Session Summary

• Problem: Pre-commit hooks appeared to run but didn't modify files
• Investigation: 45 minutes of systematic debugging
• False leads: Initially blamed merge conflicts, then tool versions
• Root cause: Cloud sync (OneDrive) file locks preventing hook modifications
• Solution: Exponential backoff retry logic for file I/O
• Outcome: Hooks now work reliably, even with cloud storage

Extraction Process

Step 1: Session Analysis

What happened:

• Started with cryptic error ("hooks ran but nothing changed")
• Checked merge conflicts (false lead)
• Checked tool versions (false lead)
• Eventually realized issue was file I/O timing
• Solution: Add retry logic with exponential backoff

What was learned:

• Cloud sync file locks cause silent I/O failures
• Need defensive file I/O with retries
• Error messages should be more diagnostic
• Cloud-related issues are often invisible

Step 2: Create Discovery Entry

````markdown

Pre-commit Hooks Cloud Sync Issue (2025-11-08)

Issue

Pre-commit hooks appeared to run but didn't modify files. No error messages, just silent failure.

Root Cause

OneDrive (cloud sync) was holding file locks on hook-modified files. The subprocess.run() call would complete "successfully" without actually writing changes because of the lock.

Solution

Implemented exponential backoff retry logic for file I/O:

def write_with_retry(filepath, data, max_retries=3):
    retry_delay = 0.1
    for attempt in range(max_retries):
        try:
            filepath.parent.mkdir(parents=True, exist_ok=True)
            filepath.write_text(data)
            return
        except OSError as e:
            if e.errno == 5 and attempt < max_retries - 1:
                time.sleep(retry_delay)
                retry_delay *= 2
            else:
                raise

````

Key Learnings

1. Cloud sync issues are silent: Tools don't report locks, operations appear to succeed 2. File I/O needs defensive coding: Always add retry logic for file operations 3. Debugging methodology matters: Systematic check of each layer (hooks → versions → I/O) 4. Environment-specific issues: Development machines with cloud sync need different handling

Prevention

For any file I/O operation:

1. Use write_with_retry() for all file modifications 2. Add explicit error logging if retries occur 3. Test with cloud storage enabled 4. Document that system expects possible brief I/O delays 5. Consider adding diagnostic flag: --verbose-io to show retry attempts

### Step 3: Quality Checklist

- ✅ Issue is specific (not "tools broken")
- ✅ Root cause identified (OneDrive file locks, not merge conflicts)
- ✅ Solution is working (now used in production)
- ✅ Learning is generalized (applies to all file I/O)
- ✅ Prevention strategy is actionable (use retry logic)
- ✅ Code examples provided
- ✅ No speculation or future-proofing

## Related Knowledge

### Discovery Connects To
- **PATTERNS.md**: "Resilient File I/O with Cloud Sync Resilience"
  - General solution for file I/O with retry logic
  - Applicable beyond just pre-commit hooks

### Could Enable New Agent
- **Agent**: "cloud-sync-issue-detector"
  - Detects when I/O errors are cloud-related
  - Suggests diagnostic approach
  - Value: Saves 30-45 minutes debugging time

## Impact

**Before extraction**:
- Developer encounters hook failure → 45 min debug → discovery
- Next developer encounters same issue → another 45 min debug

**After extraction**:
- Developer reads DISCOVERIES.md → sees root cause
- Implements retry logic → issue solved
- Time: 10 minutes vs 45 minutes = 80% improvement

**Organization impact**:
- If issue happens 4x per year: saves 140 minutes per year
- If pattern extracted: saves across multiple issues
- If agent created: saves 2-3 hours per quarter

## Key Principle

Good discoveries transform individual debugging work into organizational knowledge that prevents future mistakes and accelerates solutions.

Knowledge Extraction Example: Pattern

Scenario

After successfully implementing module regeneration strategy that has proven effective across multiple module implementations.

Session Summary

• Problem: Modules becoming tightly coupled, hard to regenerate without breaking connections
• Attempts: Tried various approaches over multiple implementations
• Solution: Brick & studs design with explicit all public API
• Success: Applied to 5+ modules, each successfully regeneratable
• Recognition: Pattern emerged as reusable solution

Extraction Process

Step 1: Session Analysis

What worked:

• Defining clear public interface via all
• Single responsibility per module
• Comprehensive test coverage
• Working examples included
• Type hints on all exports

What didn't work:

• Implicit public APIs (hard to regenerate)
• Complex interdependencies
• Missing documentation
• Scattered examples

What was learned:

• Explicitness is critical for regeneration
• all is "studs" that others connect to
• Tests define contract behavior
• Single responsibility enables independence

Step 2: Create Pattern Entry

````markdown

Pattern: Bricks & Studs Module Design with Clear Public API

Challenge

Modules become tightly coupled with implicit dependencies. When code needs regeneration or replacement, unclear public interfaces cause connections to break.

Solution

Design modules as self-contained "bricks" with explicit "studs" (public API):

Brick = Self-contained module with ONE clear responsibility Stud = Public interface that other modules connect to Regeneratable = Can be rebuilt from specification without breaking connections

Key elements:

1. Explicit all\\\\ - Defines exact public interface 2. Single Responsibility - Module does ONE thing well 3. Type Hints - All exported functions fully typed 4. Comprehensive Tests - Tests verify public contract, not implementation 5. Working Examples - Usage examples in /examples directory

Example module structure:

# __init__.py - ONLY public exports
from .core import primary_function, secondary_function
from .models import InputModel, OutputModel

__all__ = [
    'primary_function',
    'secondary_function',
    'InputModel',
    'OutputModel',
]

````

Example public function:

def primary_function(input_model: InputModel) -> OutputModel:
    """One-line summary.

    Detailed description of what this does.

    Args:
        input_model: Type and constraints

    Returns:
        Description of return type

    Raises:
        ValueError: When and why
    """
    # Implementation (could be anything)

Key Points

• Explicit all\\\\: Others know exact connection points
• Single responsibility: Easy to understand and rebuild
• Type hints throughout: Clear contracts prevent mistakes
• Test public interface: Tests verify "studs", not implementation
• Examples must work: Validates public API is usable
• Regeneratable: New implementation maintains all connections

When to Use

• Creating any new utility module
• Refactoring to improve boundaries
• Modules that might be regenerated by AI
• Shared functionality used across codebase
• System-level utilities or core modules

When NOT to Use

• Throwaway scripts (overkill)
• Highly experimental code (premature optimization)
• Prototypes that will be rewritten anyway

Real Impact

Successfully applied pattern to 5+ modules:

1. Prerequisites Module (428 lines)

• Clear public API with 5 exports
• Zero dependencies (stdlib only)
• Comprehensive tests (70 tests, 2 seconds runtime)
• Can be dropped into any project

2. Session Management Module

• Clear public contract with 8 exports
• Internal implementation changed 3x, public API stable
• Other modules only depend on public studs
• Easy to regenerate without breaking anything

3. Caching Module

• Explicit public API prevents misuse
• Internal optimization without affecting callers
• Tests verify contract, not implementation
• AI can rebuild if performance needs improvement

Related Patterns

• Module Regeneration Structure: Enables rebuilding
• Zero-BS Implementation: Implementation must work
• Parallel Task Execution: Modules can be developed in parallel
• Standard Library Only: Core modules stay dependency-free

Benefits

✅ Modules can be rebuilt independently ✅ Clear contracts prevent integration bugs ✅ Easy to replace implementations ✅ Tests verify public behavior, not implementation ✅ Documentation focuses on what, not how ✅ Other modules depend on stable interfaces

Trade-offs

• More verbose than implicit APIs
• Upfront work defining interfaces
• Must maintain all as requirements change

Integration

This pattern is now standard for all new modules in the system. Update CLAUDE.md builder agent instructions to reference this pattern.

Examples

See real implementations:

• ~/.amplihack/.claude/tools/amplihack/prerequisites.py (428 lines)
• ~/.amplihack/.claude/tools/amplihack/session/ (multi-file module)
• ~/.amplihack/.claude/tools/amplihack/caching/ (advanced caching)

### Step 3: Quality Checklist

- ✅ Pattern is general (applies to many modules)
- ✅ Proven track record (used in 5+ modules successfully)
- ✅ When/when-not-to-use is clear
- ✅ Working code examples provided
- ✅ Benefits and trade-offs documented
- ✅ Related patterns cross-referenced
- ✅ Real usage examples linked

## Related Knowledge

### Pattern Connects To
- **DISCOVERIES.md**: "Module Regeneration Structure Success"
  - How we discovered this pattern works
  - Problems it solved

### Could Enable New Agent
- **Agent**: "module-spec-generator"
  - Creates specs from code analysis
  - Ensures modules follow brick philosophy
  - Validates __all__ exports are complete

### Integration Points
- Builder agent uses this pattern for all new modules
- Reviewer agent verifies compliance
- Tester agent validates public contract
- Documentation first follows this pattern

## Impact

**Before pattern extraction**:
- Each module designed differently
- Inconsistent public interfaces
- Hard to predict breaking changes
- Difficult to regenerate modules
- High integration friction

**After pattern extraction**:
- Consistent module structure
- Clear stable interfaces
- Easy to identify breaking changes
- Simple to regenerate
- Minimal integration friction

**Organization impact**:
- 5+ modules using pattern
- 2-3 hours saved per new module (clear design)
- 50% reduction in integration bugs
- Enables AI-driven regeneration

## Key Principle

When a solution proves successful across multiple applications, extract it as a pattern. Patterns codify knowledge that improves consistency, reduces mistakes, and accelerates future work.

Knowledge Extractor Skill

Quick Start

The knowledge-extractor skill automatically extracts, synthesizes, and preserves organizational knowledge from conversations, debugging sessions, and problem-solving work.

What It Does

Converts ephemeral session context into persistent knowledge that improves future performance:

1. Extracts Discoveries: Problems solved, root causes identified, solutions implemented 2. Captures Patterns: Reusable solutions applicable to multiple situations 3. Identifies Agents: Repeated workflows that should be automated

When to Use

Extract Discoveries (After solving complex problems)

Claude, extract what we learned from this debugging session.
Update DISCOVERIES.md with root causes and solutions.

Extract Patterns (After implementing proven solutions)

What patterns should we capture from this implementation?
Update PATTERNS.md with reusable approaches.

Identify New Agents (After repeating same workflow 2+ times)

We've debugged CI failures multiple times with the same process.
Should we create a new agent to automate this?

Full Knowledge Extraction

Perform complete knowledge extraction on this session.
Extract discoveries, patterns, and agent recommendations.

Real-World Examples

Example 1: Bug Fix Knowledge Extraction

After debugging pre-commit hook failure (45 minutes):

User: Extract what we learned from fixing the pre-commit issue.

Claude:
1. Analyzes the debugging session
2. Identifies root cause: Cloud sync file locks
3. Finds solution: Exponential backoff retry logic
4. Creates DISCOVERIES.md entry with prevention strategy
5. Suggests new pattern for "Resilient File I/O"

Result: Next time pre-commit hook fails, developers reference DISCOVERIES.md and fix in 10 minutes instead of 45.

Example 2: Pattern Discovery

After implementing module regeneration strategy (multiple sessions):

User: Extract the pattern from this module design approach.

Claude:
1. Analyzes successful implementations
2. Identifies pattern: Brick & studs with __all__ exports
3. Documents reusable approach in PATTERNS.md
4. Includes working examples
5. Notes when/when-not-to-use

Result: Next module automatically uses brick philosophy without rethinking architecture.

Example 3: Agent Automation Opportunity

After debugging CI failures for the 3rd time (same 5-step process):

User: We keep using the same CI debugging process. Should we automate?

Claude:
1. Recognizes repeated workflow (3+ times)
2. Calculates time savings: 45 min → 15 min per failure
3. Recommends new agent: ci-diagnostic-workflow
4. Provides creation plan with scope and boundaries

Result: New agent automates diagnosis, saves hours per quarter.

Knowledge Types

Type 1: Discoveries

What: Problems encountered, root causes, solutions Where: DISCOVERIES.md When to extract: After solving any complex bug or issue Format: Issue → Root Cause → Solution → Learning → Prevention

Type 2: Patterns

What: Proven solutions applicable to multiple situations Where: PATTERNS.md When to extract: When solution applies to 2+ different problems Format: Challenge → Solution → Key Points → When to Use

Type 3: Agents

What: Automated workflows for repeated tasks Where: .claude/agents/amplihack/specialized/ When to extract: Workflow repeated 2+ times, saves 30+ minutes Format: Problem → Scope → Process → Value

Quality Standards

Discoveries Must Have

• ✅ Specific problem (not generic)
• ✅ Root cause identified (why, not just what)
• ✅ Working solution with code examples
• ✅ Generalizable learning
• ✅ Actionable prevention strategy

Patterns Must Have

• ✅ Clear problem statement
• ✅ Proven track record (used successfully 2+ times)
• ✅ Working code examples
• ✅ Clear when/when-not-to-use guidance
• ✅ Cross-references to related patterns

Agents Must Justify

• ✅ Repeated 2+ times (not just once)
• ✅ Takes 30+ minutes per execution
• ✅ Well-defined scope and boundaries
• ✅ Clear inputs/outputs
• ✅ Estimated time savings 2x+

Integration with System

With DISCOVERIES.md

• Prevents repeating same mistakes
• Immediate availability to all agents
• Acts as searchable knowledge base
• Updated continuously as patterns emerge

With PATTERNS.md

• Catalog of proven solutions
• Referenced in agent instructions
• Used for documentation and teaching
• Improved over time with usage data

With Agent System

• New agents fill automation gaps
• Reduce manual effort for common workflows
• Extend orchestration capabilities
• Improve system efficiency

With Session Reflection

• Automatic extraction at session end
• Preserves learnings before context loss
• Builds organizational memory
• Continuous improvement engine

Workflow Integration

Step 1: Session Analysis

Review conversation for learnings, patterns, repeated actions

Step 2: Pattern Recognition

Identify which knowledge type(s) apply

Step 3: Knowledge Extraction

Create structured entries in appropriate locations

Step 4: Quality Verification

Ensure entries meet quality standards

Step 5: Integration

Make knowledge available to agents/systems

Common Extraction Scenarios

Time Savings

Without Knowledge Extraction

• Debug same issue multiple times: 45 min × N
• Rediscover solutions: 30 min per solution
• Manual workflows: 40 min each

With Knowledge Extraction

• Reference DISCOVERIES.md: 10 min
• Apply PATTERNS.md solution: 15 min
• Use automated agent: 5 min

Example: Extracting knowledge from 1-hour debugging session saves ~4 hours over next quarter through prevention + pattern reuse.

Getting Started

Quick Extraction

"Extract what we learned from solving this problem."
→ Claude automatically identifies discoveries, patterns, agents
→ Updates appropriate knowledge bases

Targeted Extraction

"Extract a pattern for [specific solution]"
→ Claude analyzes and documents pattern
→ Updates PATTERNS.md with working examples

Full System Extraction

"Perform complete knowledge extraction"
→ Claude extracts all discoveries, patterns, agent opportunities
→ Updates DISCOVERIES.md, PATTERNS.md
→ Recommends new agents if applicable

Success Metrics

• Discoveries Used: % of DISCOVERIES entries preventing mistakes (target 80%+)
• Patterns Applied: % of problem-solving using PATTERNS.md (target 70%+)
• Agent ROI: % of repeated tasks using agents (target 60%+)
• Time Saved: Hours saved through knowledge reuse (target N hours/week)
• Error Reduction: Repeat mistakes eliminated (target 95%+)

Key Principle

Every session creates knowledge worth preserving. Without active extraction, that knowledge is lost when conversation ends. Knowledge extraction converts individual learning into organizational capability.

---

For detailed instructions, see SKILL.md