agentic-sdlc 1.0.0 → 1.5.0

package/.agent/knowledge-base/AUTO-LEARNING-GUIDE.md

@@ -0,0 +1,327 @@
+# 🧠 Auto-Learning System - Quick Start Guide
+
+## What is Auto-Learning?
+
+The auto-learning system automatically captures knowledge from every task, issue, and bug fix to build project intelligence. This creates a self-improving system that learns from experience.
+
+---
+
+## 🚀 Quick Start (3 Steps)
+
+### Step 1: Check if Learning is Required
+After completing ANY task, ask yourself:
+
+```markdown
+### Auto-Learn Check
+- [ ] Bug priority medium or higher?
+- [ ] Required 3+ attempts?
+- [ ] Same error occurred before?
+- [ ] Implementation took 4+ hours?
+- [ ] Security or performance issue?
+
+**Result:** [YES/NO]
+```
+
+### Step 2: Create Knowledge Entry (if YES)
+```bash
+# Copy template
+cp .agent/templates/Knowledge-Entry-Template.md \
+   .agent/knowledge-base/[category]/[severity]/KB-$(date +%Y-%m-%d)-[###]-[title].md
+
+# Fill in the template
+# Set "Auto-Generated: Yes"
+# Set "Source Task: [Your Task ID]"
+```
+
+### Step 3: Sync to Neo4j Knowledge Graph
+```bash
+# Automatically sync your entry to Neo4j
+python tools/neo4j/sync_skills_to_neo4j.py
+
+# Verify sync and explore relationships
+python tools/neo4j/query_skills_neo4j.py --all-skills
+```
+
+**What Neo4j Extracts:**
+- Skills mentioned in your entry
+- Technologies used
+- Relationships between skills
+- Learning paths and prerequisites
+- Author expertise mapping
+
+### Step 4: Update Index
+Add entry to `.agent/knowledge-base/INDEX.md`:
+- Update statistics
+- Add to recent entries
+- Add to category table
+- Add to technology search
+- Add to tag search
+
+**Note:** Neo4j sync is automatic - no manual indexing needed for graph queries!
+
+---
+
+## 📋 Auto-Learning Triggers
+
+| Trigger | Action | Priority |
+|---------|--------|----------|
+| 🐛 Bug Fixed (Medium+) | Create KB entry | High |
+| 🔄 3+ Attempts | Create KB entry | High |
+| 🔁 Recurring Error | Create KB entry | Critical |
+| ⏱️ 4+ Hours Work | Create KB entry | Medium |
+| 🔒 Security Issue | Create KB entry | Critical |
+| ⚡ Performance Fix | Create KB entry | Medium |
+| 🔗 Integration Issue | Create KB entry | Medium |
+| 🏗️ Architecture Decision | Create KB entry | High |
+| 🚨 Rollback Event | Create KB entry | Critical |
+
+---
+
+## 🎯 Role-Specific Quick Actions
+
+### @DEV
+```markdown
+## After Bug Fix
+1. Check severity: [critical/high/medium/low]
+2. If medium+: Create KB entry
+3. Document: Problem → Root Cause → Solution → Prevention
+4. Tag: #bug-pattern #[technology] #auto-learned
+```
+
+### @DEVOPS
+```markdown
+## After Deployment Issue
+1. Document: What failed → Why → How fixed
+2. Create KB entry in platform-specific/
+3. Add monitoring/alert recommendations
+4. Tag: #deployment #infrastructure #auto-learned
+```
+
+### @TESTER
+```markdown
+## After Finding Edge Case
+1. Document: Test scenario → Expected vs Actual → Root cause
+2. Create KB entry in bugs/ or features/
+3. Add regression test details
+4. Tag: #testing #edge-case #auto-learned
+```
+
+### @SECA
+```markdown
+## After Security Issue
+1. Document: Vulnerability → Impact → Fix → Prevention
+2. Create KB entry in security/
+3. Add detection strategy
+4. Tag: #security #vulnerability #auto-learned
+```
+
+---
+
+## 🔍 Search Before Starting
+
+**ALWAYS search knowledge base before starting work:**
+
+### Option 1: Automated Research Agent (Recommended)
+```bash
+# Searches both file system AND Neo4j automatically
+python tools/research/research_agent.py --task "your task" --type feature
+
+# Output includes:
+# - File-based KB entries
+# - Neo4j graph relationships
+# - Related technologies and skills
+# - Confidence level
+```
+
+### Option 2: Neo4j Graph Query
+```bash
+# Find skills for technology
+python tools/neo4j/query_skills_neo4j.py --tech "React"
+
+# Find related skills
+python tools/neo4j/query_skills_neo4j.py --skill "Authentication"
+
+# Search by keyword
+python tools/neo4j/query_skills_neo4j.py --search "performance"
+```
+
+### Option 3: Manual File Search
+```markdown
+### KB Search
+**Keywords:** [error message, technology, component]
+**Category:** [bugs/features/architecture/security/performance]
+**Results Found:** [number]
+
+#### Relevant Entries:
+1. KB-[ID]: [Title] - Relevance: [high/medium/low]
+   - **Solution:** [Brief summary]
+   - **Applicable:** [yes/no]
+
+2. KB-[ID]: [Title] - Relevance: [high/medium/low]
+   - **Solution:** [Brief summary]
+   - **Applicable:** [yes/no]
+```
+
+**See [Research Agent Documentation](../../tools/research/README.md) for complete guide.**
+
+---
+
+## 📝 Quick Template
+
+Use this minimal template for fast knowledge capture:
+
+```markdown
+# KB-[YYYY-MM-DD]-[###] - [Title]
+
+**Auto-Generated:** Yes  
+**Source:** [Task ID]  
+**Category:** [Category]  
+**Severity:** [Severity]
+
+## Problem
+[What went wrong]
+
+## Root Cause
+[Why it happened]
+
+## Solution
+[What fixed it]
+
+```code
+[Code snippet]
+```
+
+## Prevention
+- [How to avoid]
+- [How to detect early]
+
+## Tags
+#auto-learned #[category] #[technology]
+```
+
+---
+
+## 🎓 Learning Categories
+
+| Category | When to Use | Location |
+|----------|-------------|----------|
+| **Bugs** | Any bug fix | `bugs/[severity]/` |
+| **Features** | Complex implementation | `features/[type]/` |
+| **Architecture** | Design decision | `architecture/` |
+| **Security** | Security issue | `security/` |
+| **Performance** | Optimization | `performance/` |
+| **Platform** | Platform-specific | `platform-specific/[platform]/` |
+
+---
+
+## 📊 Quality Checklist
+
+Before saving KB entry, verify:
+
+- [ ] Clear problem description
+- [ ] Root cause explained
+- [ ] Working solution documented
+- [ ] Code snippets included
+- [ ] Prevention measures listed
+- [ ] Proper category and severity
+- [ ] Relevant tags added
+- [ ] Source task referenced
+- [ ] Index updated
+
+---
+
+## 🔄 Weekly Maintenance
+
+Every Friday, @REPORTER should:
+
+1. **Review** all auto-generated entries
+2. **Verify** completeness and quality
+3. **Add** missing details
+4. **Update** cross-references
+5. **Archive** duplicates
+
+---
+
+## 💡 Pro Tips
+
+### Tip 1: Be Specific
+❌ Bad: "Fixed login bug"  
+✅ Good: "Fixed OAuth token refresh race condition in login flow"
+
+### Tip 2: Include Error Messages
+Always include exact error messages for searchability:
+```
+Error: Cannot read property 'user' of undefined
+```
+
+### Tip 3: Document Failed Attempts
+Don't just document what worked - document what DIDN'T work:
+```markdown
+## What Didn't Work
+- Tried increasing timeout → Still failed
+- Tried different library → Compatibility issues
+- Tried caching → Race condition persisted
+```
+
+### Tip 4: Add Visual Aids
+Include screenshots, diagrams, or recordings when helpful.
+
+### Tip 5: Cross-Reference
+Link to related KB entries:
+```markdown
+## Related Entries
+- KB-2026-01-01-001: Similar hydration issue
+- KB-2025-12-15-042: SSR best practices
+```
+
+---
+
+## 📞 Need Help?
+
+- **What to document:** Tag @REPORTER
+- **Where to store:** Check category structure
+- **How to search:** Use index.md or grep
+- **Quality issues:** Tag @REPORTER for review
+
+---
+
+## 🎯 Success Metrics
+
+Track your learning impact:
+
+| Metric | Target | Current |
+|--------|--------|---------|
+| KB Entries Created | Growing | 1 |
+| KB Entries Referenced | >50% | - |
+| Similar Issues Prevented | >80% | - |
+| Resolution Time Reduced | >30% | - |
+
+---
+
+## 🚀 Advanced Features
+
+### Auto-Tagging
+System can suggest tags based on:
+- Error messages
+- Technology stack
+- Component names
+- File paths
+
+### Auto-Linking
+System can find related entries by:
+- Similar keywords
+- Same technology
+- Same component
+- Same error pattern
+
+### Auto-Metrics
+System tracks:
+- Most common issues
+- Fastest resolutions
+- Most referenced entries
+- Learning trends
+
+---
+
+#auto-learning #knowledge-base #quick-start #guide
+

package/.agent/knowledge-base/HOW-IT-WORKS.md

@@ -0,0 +1,365 @@
+# How the Knowledge Base Works - Simple Explanation
+
+## 🎯 The Big Idea
+
+Think of the knowledge base as a **team memory** that gets smarter over time. Every time you solve a hard problem, you write it down so you (or anyone else) can find the solution instantly next time.
+
+## 📚 Simple Analogy
+
+Imagine you're cooking:
+- **First time:** You try a recipe, burn it twice, finally get it right after 3 hours
+- **Without KB:** Next time, you start from scratch again, burn it again
+- **With KB:** You wrote down what worked, next time takes 30 minutes
+
+**That's compound learning!** Each solution makes future work easier.
+
+## 🔄 The Compound Loop
+
+```
+1. Problem → You encounter a bug or challenge
+2. Solution → You figure it out (maybe after 3 attempts)
+3. Document → You write it in the knowledge base
+4. Search → Next time, you search first
+5. Reuse → You find your old solution instantly
+6. Compound → You saved hours of work!
+```
+
+## 📁 How It's Organized
+
+```
+.agent/knowledge-base/
+├── INDEX.md                     # 📇 Quick lookup table
+├── bugs/                        # 🐛 Bug fixes
+│   ├── critical/               # 🔴 System breaking
+│   ├── high/                   # 🟠 Major issues
+│   ├── medium/                 # 🟡 Moderate issues
+│   └── low/                    # 🟢 Minor issues
+├── features/                    # ✨ Complex features
+│   ├── authentication/         # 🔐 Login, OAuth, etc.
+│   ├── performance/            # ⚡ Speed optimizations
+│   ├── integration/            # 🔌 Third-party APIs
+│   └── ui-ux/                  # 🎨 Design patterns
+├── architecture/                # 🏗️ Big decisions
+├── security/                    # 🔒 Security fixes
+├── performance/                 # 🚀 Speed improvements
+└── platform-specific/           # 📱 Platform issues
+    ├── web/                    # 🌐 Web apps
+    ├── mobile/                 # 📱 iOS/Android
+    ├── desktop/                # 💻 Desktop apps
+    └── cli/                    # ⌨️ Command line
+```
+
+## 💡 Real Example
+
+### Without Knowledge Base:
+```
+Day 1: "Why is React hydration failing?"
+→ Google for 2 hours
+→ Try 5 different solutions
+→ Finally fix it
+
+Day 30: Same error on different project
+→ Google for 2 hours again
+→ Try same 5 solutions again
+→ Waste another 2 hours
+```
+
+### With Knowledge Base:
+```
+Day 1: "Why is React hydration failing?"
+→ Google for 2 hours
+→ Try 5 different solutions
+→ Finally fix it
+→ Write it in KB: bugs/high/KB-2026-01-01-react-hydration.md
+
+Day 30: Same error on different project
+→ Search KB: "react hydration"
+→ Find your old solution
+→ Fix in 5 minutes
+→ Saved 1 hour 55 minutes!
+```
+
+## 📝 What Goes in the Knowledge Base?
+
+### ✅ DO Document:
+- **Hard bugs** - Took 3+ attempts to fix
+- **Tricky features** - Non-obvious implementation
+- **Performance issues** - Required investigation
+- **Security fixes** - Important to remember
+- **Architecture decisions** - Why you chose X over Y
+- **Platform quirks** - iOS vs Android differences
+
+### ❌ DON'T Document:
+- Simple typos
+- Obvious solutions (just Google it)
+- One-time issues that won't recur
+- Things already well-documented elsewhere
+
+## 🔍 How to Search
+
+### Method 1: Browse by Category
+```
+Need authentication help?
+→ Look in features/authentication/
+
+Found a critical bug?
+→ Look in bugs/critical/
+
+Performance issue?
+→ Look in performance/
+```
+
+### Method 2: Search INDEX.md
+```
+Open: .agent/knowledge-base/INDEX.md
+Search (Ctrl+F): "react hydration"
+→ Find: KB-2026-01-01-001-react-hydration.md
+→ Open and read solution
+```
+
+### Method 3: File Search
+```
+In your IDE:
+Search all files for: "hydration error"
+→ Finds all KB entries mentioning it
+```
+
+## 📄 Entry Format (Simple)
+
+Every entry has:
+
+```markdown
+---
+title: "React Hydration Mismatch Error"
+category: bug
+priority: high
+date: 2026-01-01
+tags: [react, ssr, hydration]
+---
+
+## Problem
+React shows "Hydration failed" error in production
+
+## What I Tried (That Didn't Work)
+1. Cleared cache - didn't help
+2. Reinstalled node_modules - didn't help
+3. Changed React version - didn't help
+
+## Solution (What Actually Worked)
+The issue was server/client date formatting mismatch.
+
+Fixed by:
+1. Use same date format on server and client
+2. Add suppressHydrationWarning for dynamic content
+
+## Code
+```jsx
+<time suppressHydrationWarning>
+  {new Date().toISOString()}
+</time>
+```
+
+## Prevention
+Always use ISO format for dates in SSR apps
+```
+
+## 🎯 When to Use It
+
+### Before Starting Work:
+```
+You: "I need to add OAuth login"
+→ Search KB: "oauth authentication"
+→ Find: KB-2025-12-15-oauth-implementation.md
+→ Read how it was done before
+→ Reuse the pattern
+→ Save 3 hours!
+```
+
+### After Solving Hard Problem:
+```
+You: "Finally fixed that memory leak after 4 hours!"
+→ Write it down in KB
+→ Next person (or future you) finds it instantly
+→ Team saves 4 hours next time
+```
+
+### During Code Review:
+```
+Reviewer: "Why did you do it this way?"
+You: "See KB-2025-12-20-why-we-use-redis.md"
+→ Clear explanation already documented
+→ No need to explain again
+```
+
+## 📊 The Compound Effect
+
+### Month 1:
+- 5 entries in KB
+- Saved 2 hours total
+
+### Month 3:
+- 20 entries in KB
+- Saved 15 hours total
+
+### Month 6:
+- 50 entries in KB
+- Saved 40 hours total
+
+### Year 1:
+- 150 entries in KB
+- Saved 200+ hours total
+
+**Each entry makes the next one more valuable!**
+
+## 🚀 Quick Start
+
+### Step 1: Search First
+Before solving any problem:
+```
+1. Open .agent/knowledge-base/INDEX.md
+2. Search for keywords
+3. Check if someone solved it before
+```
+
+### Step 2: Document After
+After solving a hard problem:
+```
+1. Copy template: .agent/templates/Knowledge-Entry-Template.md
+2. Fill in: Problem, Solution, Prevention
+3. Save in correct folder
+4. Add to INDEX.md
+```
+
+### Step 3: Share
+```
+Tell your team:
+"I added KB-2026-01-01-005 about OAuth refresh tokens"
+→ Everyone benefits
+```
+
+## 🎓 Learning Path
+
+### Week 1: Consumer
+- Just search and read existing entries
+- Learn from past solutions
+
+### Week 2: Contributor
+- Start adding your own entries
+- Document 1-2 problems you solve
+
+### Week 3: Curator
+- Update old entries with new info
+- Link related entries together
+
+### Month 2: Expert
+- Knowledge base becomes second nature
+- Search before Google
+- Team productivity increases
+
+## 💪 Benefits
+
+### For You:
+✅ Never solve the same problem twice
+✅ Build your personal knowledge library
+✅ Become faster over time
+✅ Look like a genius (you remember everything!)
+
+### For Team:
+✅ New members get up to speed faster
+✅ Consistent solutions across projects
+✅ Less time wasted on known issues
+✅ Institutional knowledge preserved
+
+### For Project:
+✅ Faster development
+✅ Fewer bugs
+✅ Better quality
+✅ Lower costs
+
+## 🤔 Common Questions
+
+### Q: "Isn't this just documentation?"
+**A:** No! Documentation explains how things work. KB explains how to solve problems that already happened.
+
+### Q: "Won't this take too much time?"
+**A:** Writing takes 10 minutes. Saves hours later. Math checks out!
+
+### Q: "What if I forget to search?"
+**A:** Make it a habit. Before coding, search KB. Like checking your mirrors before driving.
+
+### Q: "What if the solution is outdated?"
+**A:** Update it! KB is living documentation. Add a note: "Updated 2026-01-15: Now use v2 API"
+
+### Q: "Do I document everything?"
+**A:** No! Only hard problems (3+ attempts) or non-obvious solutions.
+
+## 🎯 Success Metrics
+
+Track your compound learning:
+
+```
+📊 My KB Stats
+- Entries Created: 12
+- Entries Reused: 8
+- Time Saved: 24 hours
+- Compound Rate: 67%
+```
+
+**Goal:** Reuse rate > 50% means KB is working!
+
+## 🔗 Integration with Roles
+
+### @DEV
+- Search KB before implementing
+- Document tricky bugs
+- Update entries with better solutions
+
+### @TESTER
+- Search for known test patterns
+- Document edge cases
+- Link test failures to KB
+
+### @SA
+- Document architecture decisions
+- Reference KB in designs
+- Update patterns as they evolve
+
+### @SECA
+- Document security fixes
+- Create prevention checklists
+- Maintain security KB
+
+## 🎉 The Magic
+
+After 6 months of using KB:
+
+**Before:**
+- "How do I fix this?" → 2 hours of Googling
+- "I solved this before..." → Can't remember how
+- "New team member" → Takes weeks to learn
+
+**After:**
+- "How do I fix this?" → 5 minutes in KB
+- "I solved this before!" → Found in 30 seconds
+- "New team member" → Reads KB, productive in days
+
+**That's the power of compound learning!** 🚀
+
+---
+
+## 📚 Next Steps
+
+1. **Read:** Browse existing entries in `.agent/knowledge-base/`
+2. **Search:** Try finding solutions in `INDEX.md`
+3. **Document:** Write your first entry after solving a problem
+4. **Share:** Tell your team about useful entries
+
+**Remember:** Every entry makes the team smarter. Every search saves time. Every reuse compounds value.
+
+---
+
+**Version:** 1.0.0  
+**Created:** 2026-01-02  
+**Philosophy:** "Each unit of work should make the next unit easier"
+
+#knowledge-base #compound-learning #how-it-works #simple-guide