# Learned Knowledge Directory

This directory contains AI's long-term memory for your project.

## 📁 Files

### `AI_LEARNED_RULES.md`
**Purpose**: Critical rules learned from user corrections  
**Format**: Structured rules with examples and enforcement  
**Usage**: AI reads at start of EVERY task

**When to Add**:
- User corrects AI's mistake
- Same issue appears multiple times
- User says "remember this" or "don't do that again"

**Rule Priority**:
- 🔴 **Critical**: NEVER violate (blocks commit if broken)
- 🟡 **High Priority**: Important but can override with justification

---

### `USER_PREFERENCES.md`
**Purpose**: Your working style and preferences  
**Format**: Structured preferences by category  
**Usage**: AI adapts to YOUR style

**When to Update**:
- You prefer different communication style
- You want different automation level
- Your tools or workflow changes

---

## 🚀 Quick Start

### Adding Your First Rule

When AI makes a mistake you've corrected before:

1. **Identify the pattern**: What keeps going wrong?
2. **Extract the lesson**: What should AI do instead?
3. **Write the rule**: Use this format:

```markdown
### RULE-XXX: [Clear Title]

**Learned From**: 2025-11-05 - Feature X implementation
**User Quote**: "[Your exact feedback]"

**The Rule**:
[What AI must/must not do]

**Why This Rule Exists**:
- [The problem]
- [The impact]

**Actions Required**:
1. ✅ [Step 1]
2. ✅ [Step 2]

**Examples**:
✅ Good: [Correct behavior]
❌ Bad: [Incorrect behavior]
```

4. **Test it**: AI should follow the rule on next task

---

## 💡 Example Rules (From Real Projects)

### Example 1: Testing Rule
```markdown
RULE-001: Browser Testing MANDATORY for UI Changes

Learned From: Bug escaped to production
User Quote: "Why didn't you test in browser?"

The Rule: For ANY UI-related changes, browser testing is MANDATORY

Actions:
1. ✅ Navigate to page
2. ✅ Verify visual changes
3. ✅ Take screenshot
4. ✅ Document results
```

### Example 2: Workflow Rule
```markdown
RULE-002: Auto-Commit When Ready

Learned From: User had to remind "why not commit?"
User Quote: "Just commit when it's ready!"

The Rule: When state = COMMIT_READY, commit immediately

Actions:
1. ✅ Check git status
2. ✅ Stage changes
3. ✅ Commit with message
4. ✅ Report completion
```

---

## 📊 Measuring Effectiveness

Track your rules' impact:

| Rule | Times Applied | Bugs Prevented | Time Saved |
|------|---------------|----------------|------------|
| RULE-001 | 5 | 1 | 2 hours |
| RULE-002 | 3 | 0 | 30 min |

**Total ROI**: [Calculate time saved vs time invested]

---

## 🎯 Best Practices

### DO ✅:
- Write specific, actionable rules
- Include examples (good vs bad)
- Reference exact user quotes
- Update when patterns change

### DON'T ❌:
- Write vague rules ("be better")
- Skip the "why" explanation
- Forget to enforce rules
- Let rules become outdated

---

## 🔄 Maintenance

### Weekly:
- Review if rules are being followed
- Update effectiveness tracking

### Monthly:
- Archive outdated rules
- Refine frequently violated rules
- Consolidate similar rules

### When User Corrects:
- **Immediately** extract rule
- Add to AI_LEARNED_RULES.md
- Verify AI reads it next task

---

## 📚 Learning Resources

- **Case Study**: See [md2social](https://github.com/trieu/md2social) for a real-world learning system (12 rules, 5x ROI)
- **Template**: This directory provides templates
- **Support**: Generated by @trieu/ai-workflow-engine

---

**Remember**: This is YOUR AI's memory. The more you teach it, the better it serves you! 🧠