agentic-sdlc 1.5.1 → 1.8.1

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

@@ -1,327 +0,0 @@
-# 🧠 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

@@ -1,365 +0,0 @@
-# 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