Learning Capture

This skill provides patterns for capturing learnings at the right moments and routing them to the right places. Learnings compound over time - the more you capture, the more future work benefits.

Three Trigger Points

Learnings should be captured at three key moments, each with different depth and focus:

1. After Chat Session (Lightweight)

When: At the end of any significant agentic coding session

Focus: Quick capture of immediate insights

• •What did we learn?
• •What should be documented?
• •Any quick process improvements?

Depth: Brief, 2-5 bullet points Time: 2-5 minutes

Example Output:

## Session Learning: 2026-01-25

- Discovered that the auth middleware requires explicit error handling
- Found undocumented API endpoint at `/internal/health`
- Process improvement: Always check existing tests before writing new ones

2. After Project Completion (Comprehensive)

When: At project milestones or completion

Focus: Thorough retrospective

• •What worked well?
• •What didn't work?
• •What to do differently next time?

Depth: Full retrospective with multiple sections Time: 15-30 minutes

Sections to Cover:

• •Project summary and outcomes
• •What went well (successes, effective practices)
• •What could be improved (challenges, pain points)
• •Process improvements (suggested changes)
• •Template refinements (updates needed)
• •Action items (next steps)

3. After Overcoming Blockers (Targeted)

When: Immediately after solving a difficult problem

Focus: Capture while fresh

• •What was painful?
• •How was it solved?
• •How to prevent next time?

Depth: Focused on the specific blocker Time: 5-10 minutes

Sections to Cover:

• •Context: What were you trying to do?
• •Initial hypothesis: What did you think was wrong?
• •Actual root cause: What was actually wrong?
• •Solution: How was it fixed?
• •Prevention: How to avoid this in the future?

Two Output Targets

Learnings can improve two distinct areas:

Target 1: Codebase Documentation

What goes here: Project-specific knowledge

• •Patterns and gotchas for this codebase
• •Architecture decisions and rationale
• •Debugging solutions for this project
• •Troubleshooting guides
• •API quirks and workarounds

Location: [current-codebase]/docs/ (appropriate subfolder)

Subfolder Guidelines:

Target 2: Plugin/Workflow Improvements

What goes here: Process and tool improvements

• •Workflow optimizations
• •New patterns to add to skills
• •Command/agent refinements
• •Template improvements
• •Cross-project patterns

Location: Plugin repository (commands, skills, or docs)

Improvement Types:

YAML Frontmatter Schema

All learnings should include searchable frontmatter:

---
title: "Brief descriptive title"
date: YYYY-MM-DD
trigger: chat-session | project-completion | blocker-overcome
target: codebase | plugin | both
category: performance | database | integration | workflow | debugging | testing | security
tags: [relevant, searchable, keywords]
severity: critical | high | medium | low
module: "affected_module_name"
---

Field Guidelines

trigger: Which trigger point captured this learning

• •chat-session: Quick session insight
• •project-completion: Full retrospective
• •blocker-overcome: Problem solution

target: Where the improvement applies

• •codebase: This specific project
• •plugin: The playbook plugin itself
• •both: Applies to both

category: Primary classification

• •performance: Speed, efficiency issues
• •database: Data layer issues
• •integration: External service issues
• •workflow: Process issues
• •debugging: Investigation patterns
• •testing: Test-related learnings
• •security: Security-related learnings

severity: Impact level

• •critical: Must know, high impact
• •high: Important, significant impact
• •medium: Good to know
• •low: Nice to have

tags: Searchable keywords (3-7 tags)

module: Specific code module affected (if applicable)

Decision Matrix: Which Target?

Use this matrix to decide where learnings should go:

Capture Workflow

Step 1: Identify Trigger

Ask: "What kind of learning moment is this?"

• •End of session → Lightweight capture
• •Project done → Comprehensive retrospective
• •Solved hard problem → Targeted capture

Step 2: Identify Target

Ask: "Who benefits from this learning?"

• •Just this project → Codebase docs
• •Future projects/workflows → Plugin improvements
• •Both → Document in both places

Step 3: Use Appropriate Template

Use template from resources/templates/learnings.md and fill sections based on trigger type.

Step 4: Add Frontmatter

Add YAML frontmatter for searchability.

Step 5: Save to Correct Location

• •Codebase: docs/learnings/YYYY-MM-DD-topic.md
• •Plugin: Create PR to plugin repo

Integration Points

This skill supports:

• •/playbook:learnings command (primary interface)
• •/playbook:debug (captures blocker-overcome learnings)
• •/playbook:work (suggests session learnings)

Best Practices

1. •Capture while fresh - Don't wait, details fade quickly
2. •Be specific - Vague learnings don't help
3. •Include context - Future you needs to understand why
4. •Add tags generously - Makes finding easier
5. •Link to code - Reference specific files/lines when relevant
6. •Update existing docs - Sometimes better than creating new ones
7. •Review periodically - Old learnings may need updates

Every learning captured makes future work easier. Compound your knowledge.