Help us improve
Share bugs, ideas, or general feedback.
From product-playbook-for-agentic-coding
Multi-trigger, dual-target learning capture patterns. Use this skill to understand how to capture learnings at different points in the development workflow and route them to appropriate targets (codebase docs or plugin improvements). Don't use when saving session state for resumption (use session-checkpoint instead), or for analyzing chat sessions at scale (use chat-insights instead).
npx claudepluginhub daviswhitehead/product-playbook-for-agentic-coding-plugin --plugin product-playbook-for-agentic-codingHow this skill is triggered — by the user, by Claude, or both
Slash command
/product-playbook-for-agentic-coding:learning-captureThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
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.
Guides technical evaluation of code review feedback: read fully, restate for understanding, verify against codebase, respond with reasoning or pushback before implementing.
Share bugs, ideas, or general feedback.
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.
Learnings should be captured at three key moments, each with different depth and focus:
When: At the end of any significant agentic coding session
Focus: Quick capture of immediate insights
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
Session Handoff (if work continues later): Also capture state for the next session:
When: At project milestones or completion
Focus: Thorough retrospective
Depth: Full retrospective with multiple sections Time: 15-30 minutes
Sections to Cover:
When: Immediately after solving a difficult problem
Focus: Capture while fresh
Depth: Focused on the specific blocker Time: 5-10 minutes
Sections to Cover:
Learnings can improve two distinct areas:
What goes here: Project-specific knowledge
Location: [current-codebase]/docs/ (appropriate subfolder)
Subfolder Guidelines:
| Content Type | Location |
|---|---|
| Problem solutions | docs/solutions/ |
| General learnings | docs/learnings/ |
| Architecture decisions | docs/architecture/ |
| Troubleshooting | docs/troubleshooting/ |
What goes here: Process and tool improvements
Location: Plugin repository (commands, skills, or docs)
Improvement Types:
| Type | Action |
|---|---|
| Command enhancement | Update command markdown |
| New skill pattern | Add to skill SKILL.md |
| Template fix | Update resources/templates/ |
| New workflow | Create new command or skill |
When performing a deep retrospective (analyzing SpecStory session files in .specstory/history/), use these patterns to extract insights the agent missed during the session.
Signal: Same action performed multiple times without progress. How to detect: Scan for repeated file reads (same path 3+ times), repeated errors, repeated user corrections, and solution/revert cycles. What it means: The agent lacked context, had a faulty mental model, or didn't learn from previous attempts. Improvement: Add the missing context to CLAUDE.md or MEMORY.md so future sessions start with it.
Signal: User communication shifts from collaborative to directive. Severity scale:
Signal: Work that didn't contribute to the final outcome. How to detect: Compare final git diff to all changes during session, look for "let me try a different approach" patterns, count debugging cycles per issue (>2 = wasted). Improvement: Document the correct approach so future sessions don't repeat wrong paths.
Signal: Work expanded significantly beyond original request. How to detect: Compare first user message to final summary. Count files touched vs expected. Improvement: If unintentional, add scope-check trigger to MEMORY.md.
Signal: CLAUDE.md size exceeds 32,000 chars or triggers the performance warning (>40k).
How to detect: Run wc -c CLAUDE.md. Check for RESOLVED issues still inline, niche guides that belong in docs/guides/, duplicate content (e.g., test commands listed in both Quick Reference and a Common Workflows section).
Root cause: The learnings promotion workflow is additive-only — it promotes content UP to CLAUDE.md but never demotes stale content DOWN to docs/guides/ or docs/learnings/.
Improvement: Before promoting new learnings to CLAUDE.md, check size and archive stale content. Resolved issues should be moved to docs/learnings/resolved-issues.md. Niche guides should be moved to docs/guides/ with a 1-line reference in CLAUDE.md.
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 | design | generation | infrastructure
tags: [relevant, searchable, keywords]
severity: critical | high | medium | low
module: "affected_module_name"
---
trigger: Which trigger point captured this learning
chat-session: Quick session insightproject-completion: Full retrospectiveblocker-overcome: Problem solutiontarget: Where the improvement applies
codebase: This specific projectplugin: The playbook plugin itselfboth: Applies to bothcategory: Primary classification
performance: Speed, efficiency issuesdatabase: Data layer issuesintegration: External service issuesworkflow: Process issuesdebugging: Investigation patternstesting: Test-related learningssecurity: Security-related learningsdesign: Visual design, UX, branding learningsgeneration: AI content/image generation learningsinfrastructure: DevOps, CI/CD, deployment learningsseverity: Impact level
critical: Must know, high impacthigh: Important, significant impactmedium: Good to knowlow: Nice to havetags: Searchable keywords (3-7 tags)
module: Specific code module affected (if applicable)
Use this matrix to decide where learnings should go:
| Learning Type | Codebase? | Plugin? |
|---|---|---|
| Bug fix for specific code | Yes | No |
| General debugging pattern | Maybe | Yes |
| Architecture decision | Yes | No |
| Workflow improvement | No | Yes |
| Template enhancement | No | Yes |
| Cross-project pattern | Maybe | Yes |
| Project-specific gotcha | Yes | No |
| Tool usage tip | No | Yes |
Ask: "What kind of learning moment is this?"
Ask: "Who benefits from this learning?"
Use template from resources/templates/learnings.md and fill sections based on trigger type.
Add YAML frontmatter for searchability.
docs/learnings/YYYY-MM-DD-topic.mdIf session history files are available (.specstory/history/*.md):
Before promoting, check CLAUDE.md health:
wc -c CLAUDE.md to check current sizedocs/learnings/resolved-issues.mddocs/guides/Promotion hierarchy (highest = most actionable):
Demotion — content should also move DOWN the hierarchy over time:
docs/learnings/resolved-issues.mddocs/guides/This skill supports:
/playbook:learnings command (primary interface)/playbook:debug (captures blocker-overcome learnings)/playbook:work (suggests session learnings)Every learning captured makes future work easier. Compound your knowledge.