1410 Recognizing Learnings 19745db3

# Recognizing Learnings

Valuable learnings often reveal themselves through specific signals during your work. Train yourself to notice these patterns.

## Time Investment Signals

### Debugging Time
**Signal:** "I spent 20+ minutes debugging this issue"

**Questions to ask:**
- Was this documented anywhere?
- Did I search existing skills first?
- Would documenting this prevent future debugging time?
- Is this a one-off or recurring pattern?

**Example:**
```
Spent 45 minutes figuring out why Playwright tests were flaky. 
Root cause: Need to wait for network idle, not just element presence.
Pattern documented? No. Should be? Yes - common issue with webapp-testing.
```

### Trial and Error
**Signal:** "I tried 3+ approaches before finding what worked"

**Questions to ask:**
- Were the failed approaches reasonable attempts?
- What made the winning approach better?
- Could guidance have prevented the trial-and-error?

**Example:**
```
Tried git rebase -i (failed - interactive not supported)
Tried git reset (lost work)
Finally: git rebase HEAD~3 worked
Could this be documented in git-workflows? Yes.
```

### "Wish I Had Known"
**Signal:** "I wish I had known this at the start"

**Questions to ask:**
- Where would I have looked for this info?
- What skill should contain this?
- How much time would it have saved?

**Example:**
```
Spent hour implementing custom retry logic for API calls.
Later discovered: Most API libraries have built-in retry with backoff.
Should be in api-integration skill: "Check library features first"
```

## Repetition Signals

### Recurring Problem
**Signal:** "This is the third time I've solved this exact problem"

**Strong indicator** that knowledge should be captured.

**Questions to ask:**
- Am I solving it the same way each time?
- Have I refined my approach across iterations?
- Would other agents encounter this?

**Example:**
```
Third time setting up Letta agent with file system access.
Same steps each time: attach folder, verify tools appear, test read access.
Create quick-start pattern in letta-agent-designer.
```

### Deja Vu Moments
**Signal:** "I remember doing something similar before"

**Questions to ask:**
- What was different about the previous context?
- What was the same (the generalizable pattern)?
- Can I extract the common pattern?

**Example:**
```
Configuring environment variables for third different framework.
Pattern: All frameworks need .env file, loading mechanism differs.
Extract: Common env var patterns, framework-specific loading details.
```

### Teaching Moments
**Signal:** "Let me explain how this works..."

**When you explain something to a user, you're identifying knowledge worth documenting.**

**Questions to ask:**
- Did I explain this clearly?
- Would this explanation help in a skill?
- Are there examples that made it click?

**Example:**
```
Explained memory_insert vs memory_replace to user with concurrent scenario.
User understood immediately with the example.
Capture example in letta-memory-architect for future clarity.
```

## Correction Signals

### Skill Led Astray
**Signal:** "The skill said X, but Y actually works better"

**Critical learning moment - either skill is wrong or you misunderstood.**

**Questions to ask:**
- Did I follow instructions correctly?
- Are there conditions where X is right but Y is better for my case?
- Is the skill outdated or incomplete?

**Example:**
```
Skill said: "Use GPT-4 for complex tasks"
But: GPT-4o is newer, faster, same quality, lower cost
Skill needs update: GPT-4o is now preferred over GPT-4
```

### Approach Failed
**Signal:** "This approach failed in ways not documented"

**Questions to ask:**
- Was the failure predictable?
- Should the skill warn about this?
- What's the workaround?

**Example:**
```
Followed git-workflows to use git add -i (interactive add)
Failed: Interactive mode not supported in Bash tool
Add warning to skill about non-interactive environment
```

### Misunderstanding Caused Issue
**Signal:** "I misunderstood the instruction and it caused problems"

**Even if you made the mistake, ambiguous instructions should be clarified.**

**Questions to ask:**
- Would others misunderstand the same way?
- What clarification would have prevented this?
- Are there examples that would make it clearer?

**Example:**
```
Skill said: "Use appropriate model for task"
I chose GPT-4 (expensive) when GPT-4o-mini would've worked
Add decision criteria: task complexity, budget, latency needs
```

## Discovery Signals

### Gap Found
**Signal:** "I needed to know X but no skill covers it"

**Questions to ask:**
- Is this narrow domain or broadly applicable?
- Have I validated my approach?
- Would this help others or just me?

**Example:**
```
Needed to parse YAML frontmatter from markdown files.
No skill covers this common pattern in document processing.
Create: parsing-markdown skill or add to document patterns.
```

### Better Pattern Emerged
**Signal:** "I've found a better way to structure this"

**Questions to ask:**
- Better in what way? (Faster, clearer, more reliable?)
- What's the tradeoff?
- Is this preference or objective improvement?

**Example:**
```
Initially: Put all customer info in one block
Better: Split into customer_business, customer_contact, customer_history
Why: Each grows independently, clearer boundaries, easier to manage
Objective improvement: Addresses size management and clarity
```

### New Tool/Technique
**Signal:** "This tool/approach is much better than what we're using"

**Questions to ask:**
- Is this genuinely better or just different?
- What's the learning curve?
- Are there situations where old approach is still better?

**Example:**
```
Discovered ripgrep (rg) is much faster than grep for codebase search.
Already in use: Grep tool actually uses ripgrep under the hood
No action needed, but validates existing choice.
```

## False Positives to Avoid

### One-Off Edge Case
**Signal:** "This weird situation needed a weird fix"

**Usually NOT worth documenting unless:**
- Edge case is common
- Others will likely hit it
- The fix is non-obvious

### Personal Preference
**Signal:** "I prefer doing it this way"

**Only document if:**
- Preference has objective advantages
- Multiple valid approaches exist and should be explained
- Tradeoffs are worth documenting

### Temporary Workaround
**Signal:** "This hack works for now"

**Document IF:**
- Others will hit same issue
- Workaround is reliable enough
- Note it as temporary/workaround

**Don't document IF:**
- Proper fix is known and achievable
- Workaround is fragile
- Problem is specific to your environment

## Building Recognition Habit

**During work:**
- Keep mental note of "moments of friction"
- Notice when you reference external docs repeatedly
- Track time spent on recurring problems

**After completing task:**
- Review: What was hard? What took time?
- Ask: Could this be prevented next time?
- Consider: Would documenting this help others?

**Over time:**
- Pattern recognition improves
- You'll spot learnings faster
- Contributing becomes natural

## When NOT to Contribute

**CRITICAL:** Skills must be **general-purpose knowledge**, not project-specific solutions.

Sometimes the learning is valuable for you but not for the repository:

### ❌ Project-Specific Information

**Do NOT contribute:**
- Your company's API endpoints or credentials
- Configuration specific to your environment
- Project-specific file paths or structure
- Internal tool names or processes unique to your organization
- Solutions that only work in your exact setup

**Example of what NOT to contribute:**
```
"Our API endpoint for user data is https://api.acme.com/v2/users. 
Use header X-Acme-Key for authentication."

This is configuration for one specific project, not generalizable knowledge.
```

### ❌ Personal Preferences

**Do NOT contribute:**
- "I prefer approach X" without objective benefit
- Code organization that's just your style
- Tool choices based on personal taste
- Workflows that work for you but aren't broadly better

**Example of what NOT to contribute:**
```
"I like to organize my code with all API calls in src/api/ directory."

This is personal preference, not a pattern with clear advantages.
```

### ❌ One-Off Situations

**Do NOT contribute:**
- Temporary workarounds that will be obsolete soon
- One-time edge cases unlikely to recur
- Unusual situations unique to your context
- Hacks that address symptoms not root causes

**Example of what NOT to contribute:**
```
"When Docker container won't start, run docker network prune then restart."

This addresses a symptom in your environment, not a general pattern.
```

### ❌ Overly Narrow Knowledge

**Do NOT contribute:**
- How you implemented one specific feature
- Step-by-step for your exact use case
- Details that only matter in narrow contexts
- Information too specific to be broadly useful

**Example of what NOT to contribute:**
```
"How I built the user authentication for my todo app using Firebase Auth 
with Google OAuth and custom claims for role-based access."

This is one specific implementation, not teaching general patterns.
```

### ✅ What TO Contribute Instead

Transform specific learnings into general patterns:

**Bad (too specific):**
```
"Fix Docker networking issue by running docker network prune"
```

**Good (general pattern):**
```
"Debugging network connectivity in containerized environments: 
systematic approaches to isolate network vs. application issues"
```

**Bad (too specific):**
```
"Our database connection string for production"
```

**Good (general pattern):**
```
"Database connection pooling patterns and configuration strategies 
for high-traffic applications"
```

**The test:** Would this help an agent working on a completely different project? If no → too specific.

Focus contributions on **generalizable, validated, impactful learnings** that help the collective across different projects and contexts.