agentic-sdlc 1.0.0 → 1.5.0

package/docs/guides/AUTO-LEARNING-COMPLETE-GUIDE.md

@@ -0,0 +1,519 @@
+# 🧠 Complete Auto-Learning System Guide
+
+## Overview
+
+The Auto-Learning System is now fully integrated into the TeamLifecycle SDLC workflow. This guide provides a complete overview of all components and how they work together.
+
+---
+
+## 📚 System Components
+
+### 1. Core Rules & Documentation
+| Document | Purpose | Location |
+|----------|---------|----------|
+| Auto-Learning Rules | Complete system rules | `.agent/rules/auto-learning.md` |
+| Knowledge Base Rules | KB management | `.agent/rules/knowledge-base.md` |
+| Global Rules | Updated with auto-learning | `.agent/rules/global.md` |
+| Artifacts Rules | Updated with CHANGELOG rule | `.agent/rules/artifacts.md` |
+
+### 2. Knowledge Base Structure
+```
+.agent/knowledge-base/
+├── AUTO-LEARNING-GUIDE.md          # Quick start guide
+├── README.md                        # Full KB documentation
+├── index.md                         # Searchable index
+├── bugs/                            # Bug patterns by severity
+│   ├── critical/
+│   ├── high/
+│   ├── medium/
+│   └── low/
+├── features/                        # Feature implementations
+│   ├── authentication/
+│   ├── performance/
+│   ├── integration/
+│   └── ui-ux/
+├── architecture/                    # Architecture decisions
+├── security/                        # Security vulnerabilities
+├── performance/                     # Performance optimizations
+├── platform-specific/               # Platform issues
+│   ├── web/
+│   ├── mobile/
+│   ├── desktop/
+│   ├── cli/
+│   └── embedded/
+└── role-guides/                     # Role-specific KB guides
+    ├── PM-KB-Guide.md
+    ├── DEV-KB-Guide.md
+    ├── DEVOPS-KB-Guide.md
+    ├── TESTER-KB-Guide.md
+    └── SECA-KB-Guide.md
+```
+
+### 3. Templates
+| Template | Purpose | Location |
+|----------|---------|----------|
+| Knowledge Entry | Standard KB entry format | `.agent/templates/Knowledge-Entry-Template.md` |
+| CHANGELOG | Template only (not for root) | `.agent/templates/CHANGELOG-Template.md` |
+
+### 4. Workflows
+| Workflow | Purpose | Location |
+|----------|---------|----------|
+| Auto-Learning Workflow | Phase-by-phase integration | `.agent/workflows/auto-learning-workflow.md` |
+| Git + KB Integration | Git workflow integration | `.agent/workflows/git-kb-integration.md` |
+| KB Hooks Setup | Agent hooks configuration | `.agent/workflows/kb-hooks-setup.md` |
+
+### 5. Guides
+| Guide | Purpose | Location |
+|-------|---------|----------|
+| Auto-Learning System | System overview | `docs/guides/AUTO-LEARNING-SYSTEM.md` |
+| MCP Guide | MCP server integration | `docs/guides/MCP-GUIDE.md` |
+| MCP Setup | MCP configuration | `docs/guides/MCP-SETUP.md` |
+| MCP Quick Reference | MCP usage reference | `docs/guides/MCP-QUICK-REFERENCE.md` |
+
+---
+
+## 🎯 Auto-Learning by Role
+
+### @PM (Project Manager)
+**Triggers:**
+- Scope creep patterns
+- Estimation errors (>30% variance)
+- Requirements changes
+- Stakeholder conflicts
+- Risk materialization
+
+**KB Location:** `architecture/`  
+**Guide:** `.agent/knowledge-base/role-guides/PM-KB-Guide.md`
+
+---
+
+### @DEV (Developer)
+**Triggers:**
+- Bug fixes (medium+ priority)
+- 3+ implementation attempts
+- Integration challenges
+- Performance optimizations
+- Complex logic (4+ hours)
+
+**KB Location:** `bugs/`, `features/`, `performance/`  
+**Guide:** `.agent/knowledge-base/role-guides/DEV-KB-Guide.md`
+
+---
+
+### @DEVOPS (DevOps Engineer)
+**Triggers:**
+- Deployment failures
+- Rollback events
+- Infrastructure issues
+- Configuration errors
+- Performance problems
+- Security incidents
+
+**KB Location:** `platform-specific/`, `performance/`  
+**Guide:** `.agent/knowledge-base/role-guides/DEVOPS-KB-Guide.md`
+
+---
+
+### @TESTER (Tester)
+**Triggers:**
+- Test failures (3+ times)
+- Edge cases discovered
+- Regression bugs
+- Flaky tests
+- Performance bottlenecks
+- Browser compatibility issues
+
+**KB Location:** `bugs/`, `features/testing/`, `platform-specific/web/`  
+**Guide:** `.agent/knowledge-base/role-guides/TESTER-KB-Guide.md`
+
+---
+
+### @SECA (Security Analyst)
+**Triggers:**
+- Security vulnerabilities (any)
+- Security incidents
+- Auth/authorization issues
+- Data leaks
+- Compliance violations
+- Crypto issues
+
+**KB Location:** `security/`  
+**Guide:** `.agent/knowledge-base/role-guides/SECA-KB-Guide.md`
+
+---
+
+### @SA, @UIUX, @QA, @PO, @REPORTER
+**Triggers:**
+- Architecture decisions
+- Design patterns
+- UX research findings
+- Quality issues
+- Process improvements
+
+**KB Location:** `architecture/`, `features/ui-ux/`  
+**Guides:** Coming soon
+
+---
+
+## 🔄 Complete Workflow Integration
+
+### Phase 1: Planning (@PM)
+```markdown
+1. Search KB for similar projects
+2. Review estimation patterns
+3. Check risk patterns
+4. Create project plan
+5. Document planning decisions
+6. Create KB entry if estimation error >30%
+```
+
+### Phase 2: Design (@SA, @UIUX, @PO)
+```markdown
+1. Search KB for architecture patterns
+2. Review design decisions
+3. Create design specs
+4. Document architecture decisions
+5. Create KB entry for major decisions
+```
+
+### Phase 3: Design Verification (@QA, @SECA)
+```markdown
+1. Search KB for similar vulnerabilities
+2. Review security patterns
+3. Conduct reviews
+4. Document findings
+5. Create KB entry for vulnerabilities
+```
+
+### Phase 4: Development (@DEV, @DEVOPS)
+```markdown
+1. Search KB before coding
+2. Track implementation attempts
+3. Document challenges
+4. Create KB entry if 3+ attempts or medium+ bug
+5. Link KB to git commits
+```
+
+### Phase 5: Testing (@TESTER)
+```markdown
+1. Search KB for test patterns
+2. Execute tests
+3. Document failures and edge cases
+4. Create KB entry if 3+ failures
+5. Add regression tests
+```
+
+### Phase 6: Deployment (@DEVOPS)
+```markdown
+1. Search KB for deployment issues
+2. Execute deployment
+3. Monitor for issues
+4. Create KB entry for failures/rollbacks
+5. Update runbooks
+```
+
+### Phase 7: Reporting (@REPORTER)
+```markdown
+1. Review all KB entries from sprint
+2. Verify completeness
+3. Generate learning metrics
+4. Include KB summary in reports
+5. Identify knowledge gaps
+```
+
+---
+
+## 🤖 Automation Features
+
+### 1. Automatic Trigger Detection
+System automatically detects when KB entry is needed:
+- Bug priority check
+- Attempt counter
+- Error pattern matching
+- Time tracking
+- Severity assessment
+
+### 2. Auto-Tagging
+System suggests tags based on:
+- File paths → Component tags
+- Error messages → Technology tags
+- Commit messages → Category tags
+- Time spent → Complexity tags
+
+### 3. Auto-Linking
+System finds related entries by:
+- Similar error messages
+- Same file paths
+- Same technology stack
+- Same component
+- Similar keywords
+
+### 4. Auto-Metrics
+System tracks:
+- KB entries created
+- KB entries referenced
+- Resolution time trends
+- Recurring issue rates
+- Knowledge reuse rates
+
+---
+
+## 🎣 Agent Hooks
+
+### Available Hooks
+1. **Post-Commit Check** - After git commit
+2. **Bug Fix Capture** - When #fixbug- tag used
+3. **Sprint End Review** - Manual trigger
+4. **Pre-Task Search** - Before starting work
+5. **Multiple Attempts** - When file saved 3+ times
+6. **Security Issue** - When security tag used
+7. **Performance Optimization** - When performance tag used
+8. **Deployment Issue** - When deployment/rollback tag used
+9. **Weekly Maintenance** - Every Friday
+10. **Monthly Report** - Last day of month
+
+**Setup Guide:** `.agent/workflows/kb-hooks-setup.md`
+
+---
+
+## 🔗 Git Integration
+
+### Enhanced Commit Messages
+```
+<type>: <description> (#issue) [KB-###]
+
+[optional body with KB references]
+```
+
+### Example
+```
+fix: resolve hydration mismatch in Astro components (#43) [KB-2026-01-01-001]
+
+Root cause: Using Date.now() for IDs during SSR
+Solution: Switched to React 18's useId() hook
+Prevention: Added ESLint rule
+
+References KB-2026-01-01-001 for similar SSR issues
+```
+
+### PR Template with KB
+Pull requests now include KB section:
+- KB entries referenced
+- New KB entry required?
+- KB entry details
+- Key learnings
+
+**Integration Guide:** `.agent/workflows/git-kb-integration.md`
+
+---
+
+## 📊 Metrics & Analytics
+
+### Individual Metrics
+- KB entries created
+- KB entries referenced
+- Time saved
+- Issues prevented
+
+### Team Metrics
+- Total KB entries
+- Auto-generated percentage
+- Reuse rate
+- Resolution time trends
+- Recurrence rate
+
+### Sprint Metrics
+- KB entries per sprint
+- KB coverage by category
+- Most referenced entries
+- Learning velocity
+
+### Project Metrics
+- Knowledge growth over time
+- Impact on quality
+- Impact on velocity
+- Team learning curve
+
+---
+
+## 🎓 Training & Onboarding
+
+### Week 1: Learn the System
+- [ ] Read AUTO-LEARNING-GUIDE.md
+- [ ] Review example KB entry
+- [ ] Search KB for common issues
+- [ ] Shadow experienced team member
+
+### Week 2: Start Using
+- [ ] Search KB before starting tasks
+- [ ] Reference KB entries in work
+- [ ] Ask questions about KB entries
+- [ ] Identify gaps in KB
+
+### Week 3: Start Contributing
+- [ ] Create first KB entry
+- [ ] Get review from @REPORTER
+- [ ] Update index
+- [ ] Share with team
+
+### Week 4: Full Integration
+- [ ] Auto-learning becomes habit
+- [ ] Contributing regularly
+- [ ] Helping others use KB
+- [ ] Suggesting improvements
+
+---
+
+## 🚀 Quick Start Checklist
+
+### For New Projects
+- [ ] Review AUTO-LEARNING-SYSTEM.md
+- [ ] Read role-specific KB guide
+- [ ] Set up agent hooks
+- [ ] Configure git integration
+- [ ] Create first KB entry
+
+### For Existing Projects
+- [ ] Audit existing knowledge
+- [ ] Create KB entries for known issues
+- [ ] Set up automation
+- [ ] Train team
+- [ ] Start tracking metrics
+
+---
+
+## 📈 Success Criteria
+
+### Individual Success
+- [ ] Searches KB before starting work
+- [ ] Creates KB entries for qualifying tasks
+- [ ] References KB entries in artifacts
+- [ ] Updates KB entries with new insights
+- [ ] Helps others use KB
+
+### Team Success
+- [ ] 80%+ auto-learning adoption
+- [ ] 50%+ KB reuse rate
+- [ ] 30%+ resolution time reduction
+- [ ] <10% recurring issue rate
+- [ ] Growing KB with quality entries
+
+### Project Success
+- [ ] Continuous improvement culture
+- [ ] Knowledge sharing normalized
+- [ ] Faster onboarding
+- [ ] Higher quality deliverables
+- [ ] Reduced technical debt
+
+---
+
+## 🔧 Maintenance Schedule
+
+### Daily (Automated)
+- Auto-detect learning triggers
+- Auto-create KB entry drafts
+- Auto-tag entries
+- Auto-link related entries
+
+### Weekly (@REPORTER)
+- Review auto-generated entries
+- Verify completeness
+- Add missing details
+- Update cross-references
+- Archive duplicates
+- Generate weekly metrics
+
+### Monthly (@REPORTER)
+- Analyze learning metrics
+- Identify knowledge gaps
+- Consolidate similar entries
+- Update categories
+- Generate monthly report
+- Share insights with team
+
+### Quarterly (@PM + @REPORTER)
+- Review entire knowledge base
+- Archive outdated entries
+- Refactor categories
+- Update templates
+- Train team on new patterns
+- Celebrate learning wins
+
+---
+
+## 📞 Support & Resources
+
+### Need Help?
+- **What to document:** Tag @REPORTER
+- **How to search:** Check index.md or use grep
+- **Quality issues:** Tag @REPORTER for review
+- **System improvements:** Tag @PM
+- **Technical issues:** Check documentation
+
+### Documentation
+- **Quick Start:** `.agent/knowledge-base/AUTO-LEARNING-GUIDE.md`
+- **Full System:** `docs/guides/AUTO-LEARNING-SYSTEM.md`
+- **Role Guides:** `.agent/knowledge-base/role-guides/`
+- **Workflows:** `.agent/workflows/`
+- **Templates:** `.agent/templates/`
+
+### Examples
+- **Bug Fix:** `.agent/knowledge-base/bugs/medium/KB-2026-01-01-001-example-auto-learned.md`
+- **Git Integration:** `.agent/workflows/git-kb-integration.md`
+- **Hooks Setup:** `.agent/workflows/kb-hooks-setup.md`
+
+---
+
+## 🎉 System Status
+
+### ✅ Completed Components
+1. ✅ Core auto-learning rules
+2. ✅ Knowledge base structure
+3. ✅ Role-specific guides (PM, DEV, DEVOPS, TESTER, SECA)
+4. ✅ Workflow integration
+5. ✅ Git integration
+6. ✅ Agent hooks setup
+7. ✅ Templates and examples
+8. ✅ Documentation and guides
+9. ✅ MCP integration
+10. ✅ Metrics and analytics
+
+### 🚀 Ready to Use
+The auto-learning system is fully operational and ready to capture knowledge from every task, issue, and bug fix across the entire SDLC.
+
+---
+
+## 🎯 Next Steps
+
+1. **Start Using Today**
+   - Fix a bug → Create KB entry
+   - Search before starting work
+   - Reference entries in your work
+
+2. **Set Up Automation**
+   - Configure agent hooks
+   - Set up git integration
+   - Enable auto-detection
+
+3. **Train Your Team**
+   - Share this guide
+   - Review role-specific guides
+   - Practice with examples
+
+4. **Track Progress**
+   - Monitor metrics
+   - Celebrate wins
+   - Iterate and improve
+
+---
+
+**Remember:** The system gets smarter with every entry. Start documenting today!
+
+---
+
+*Version: 1.0*  
+*Last Updated: 2026-01-01*  
+*Status: Production Ready*
+
+#auto-learning #knowledge-base #complete-guide #teamlifecycle
+