sublation-os 1.0.1 → 1.1.0

package/.cursor/commands/sublation-os/consolidate-learnings.md

@@ -0,0 +1,553 @@
+---
+description: Consolidate learnings by identifying patterns and organizing them into generalized rules while maintaining examples for few-shot learning
+model: sonnet
+---
+
+You are consolidating the Sublation-OS memory system to keep learnings manageable and organized as they grow.
+
+## Your Task
+
+Analyze existing learnings across all memory files to:
+1. **Identify patterns** - Find similar learnings that can be consolidated
+2. **Create generalized rules** - Extract common principles from specific examples
+3. **Maintain examples** - Keep concrete examples for few-shot learning
+4. **Organize by pillars** - Split domain-specific learnings into pillar-based files (e.g., work, HR, finance)
+
+---
+
+## Step 1: Analyze Existing Learnings
+
+Read all memory files to understand current learnings:
+
+```
+.sublation-os/memory/
+├── backend-lessons.md
+├── frontend-lessons.md
+├── testing-lessons.md
+├── architecture-lessons.md
+├── general-lessons.md
+└── learned-lessons.md (legacy)
+```
+
+For each file:
+1. Read all entries
+2. Extract key themes and patterns
+3. Identify similar or overlapping learnings
+4. Note domain-specific learnings (e.g., "Work service", "HR module", "Finance API")
+
+---
+
+## Step 2: Identify Consolidation Opportunities
+
+Look for learnings that:
+
+### Can Be Generalized
+- **Multiple specific examples** of the same pattern
+- **Similar lessons** with different contexts
+- **Repeated tags** across multiple entries
+
+**Example:**
+```
+Entry 1: Work service bulk operations use BulkUpdateAsync
+Entry 2: HR service bulk imports use BulkUpdateAsync
+Entry 3: Finance reconciliation uses BulkUpdateAsync
+
+→ Consolidate to: "For bulk operations across services, use BulkUpdateAsync pattern"
+```
+
+### Should Be Split by domain
+Domain-specific learnings that belong to domain /business rules should be split accordingly.
+
+
+**Example:**
+```
+Entry: "Work service validates assignees before creating work items"
+→ Move to: .sublation-os/memory/pillars/work-lessons.md
+```
+
+---
+
+## Step 3: Create Consolidation Plan
+
+Before making changes, present a consolidation plan to the user:
+
+```markdown
+# Consolidation Plan
+
+## 📊 Analysis Summary
+- Total learnings analyzed: {N}
+- Consolidation opportunities found: {M}
+- Pillar-specific learnings identified: {P}
+
+## 🔄 Proposed Consolidations
+
+### Pattern 1: {Pattern Name}
+**Combining entries:** #{entry_ids}
+**Generalized rule:** {description}
+**Examples to keep:** {count} from different domains
+**Target file:** {file}
+
+### Pattern 2: {Pattern Name}
+...
+
+## 🏛️ Proposed Pillar Organization
+
+### x Pillar ({N} learnings)
+- Entry #5: Work item validation patterns
+- Entry #12: Work service bulk operations
+- Entry #18: Work assignment logic
+
+**Action:** Create `.sublation-os/memory/pillars/x-lessons.md`
+
+### y Pillar ({N} learnings)
+...
+
+## ⚠️ Risks
+- {List any potential issues with consolidation}
+
+## ✅ Benefits
+- Reduced duplication: {percentage}
+- Improved organization: {description}
+- Better searchability: {description}
+```
+
+---
+
+## Step 4: Execute Consolidation
+
+After user approval, perform the consolidation:
+
+### For Generalized Rules
+
+Create consolidated entries that:
+1. **Combine similar learnings** into one comprehensive entry
+2. **Extract the general principle**
+3. **Keep multiple examples** from different contexts
+4. **Preserve all tags** from source entries
+5. **Reference original entry numbers** for traceability
+
+**Consolidated Entry Template:**
+```markdown
+## Entry {N} - {YYYY-MM-DD HH:mm} [CONSOLIDATED]
+
+### 🧠 Context
+Consolidated from entries #{source_entry_ids}. {General context of the pattern}
+
+### 📘 Lesson
+{Generalized principle that applies across multiple scenarios}
+
+### ⚙️ Application
+{General guidelines for applying this lesson}
+
+**Specific Applications:**
+- **{Domain 1}:** {Specific application}
+- **{Domain 2}:** {Specific application}
+- **{Domain 3}:** {Specific application}
+
+### 🧩 Examples
+
+**Example 1: {Domain 1 context}**
+
+❌ **Anti-pattern:**
+```{language}
+{code}
+```
+
+✅ **Correct approach:**
+```{language}
+{code}
+```
+
+**Example 2: {Domain 2 context}**
+
+❌ **Anti-pattern:**
+```{language}
+{code}
+```
+
+✅ **Correct approach:**
+```{language}
+{code}
+```
+
+### 🏷️ Tags
+`#consolidated` `{all_original_tags}`
+
+### 📎 Source Entries
+- Entry #{id1} from {file1}
+- Entry #{id2} from {file2}
+- Entry #{id3} from {file3}
+
+---
+```
+
+### For Pillar Organization
+
+1. **Create pillar directory** if it doesn't exist:
+   ```
+   mkdir -p .sublation-os/memory/pillars/
+   ```
+
+2. **Create pillar-specific files:**
+   ```
+   .sublation-os/memory/pillars/
+   ├── work-lessons.md
+   ├── hr-lessons.md
+   ├── finance-lessons.md
+   ├── customer-lessons.md
+   └── auth-lessons.md
+   ```
+
+3. **Move domain-specific learnings** to appropriate pillar files
+
+4. **Add pillar header** to new files:
+   ```markdown
+   # {Pillar Name} Pillar Lessons
+
+   This file contains learnings specific to the {pillar name} domain and its services.
+
+   **Pillar Components:**
+   - {List main services/components in this pillar}
+
+   **Related Categories:**
+   - See [Backend Lessons](../backend-lessons.md) for general backend patterns
+   - See [Architecture Lessons](../architecture-lessons.md) for system design
+
+   ---
+   ```
+
+5. **Update source files** with references to moved entries:
+   ```markdown
+   ## Entry {N} - {date} [MOVED]
+
+   This entry has been moved to `.sublation-os/memory/pillars/{pillar}-lessons.md` as Entry {M}.
+
+   **Quick link:** See Pillar-specific lessons for {pillar} domain.
+   ```
+
+---
+
+## Step 5: Update Index
+
+Update `.sublation-os/memory/index.md` to reflect changes:
+
+1. **Add Pillar section:**
+   ```markdown
+   ### Pillar-Specific Lessons
+
+   1. **[Work Pillar](pillars/work-lessons.md)** - Work items, assignments, tracking
+   2. **[HR Pillar](pillars/hr-lessons.md)** - Employee management, payroll
+   3. **[Finance Pillar](pillars/finance-lessons.md)** - Invoicing, payments, reconciliation
+   ```
+
+2. **Update statistics:**
+   - Total learnings count
+   - Consolidated entries count
+   - Pillar distribution
+
+3. **Add consolidation tags:**
+   - `#consolidated` - For generalized rules
+   - `#pillar:{name}` - For pillar-specific learnings
+
+---
+
+## Step 6: Archive Originals
+
+Don't delete original entries immediately:
+
+1. **Create archive directory:**
+   ```
+   .sublation-os/memory/archive/{YYYY-MM-DD}/
+   ```
+
+2. **Copy original files** before consolidation:
+   ```
+   cp backend-lessons.md archive/{date}/backend-lessons.md.bak
+   ```
+
+3. **Keep for 30 days** to allow rollback if needed
+
+---
+
+## Quality Standards
+
+### When Consolidating
+
+✅ **Do:**
+- Keep all unique examples from source entries
+- Preserve file references and line numbers
+- Maintain or improve specificity
+- Add cross-references between related entries
+- Include all tags from source entries
+
+❌ **Don't:**
+- Lose valuable context or examples
+- Over-generalize to the point of being vague
+- Remove domain-specific details
+- Break file references
+
+### When Organizing by Pillars
+
+✅ **Do:**
+- Group by business domain/pillar
+- Keep related learnings together
+- Maintain category files for general patterns
+- Add clear navigation between files
+
+❌ **Don't:**
+- Create too many small pillar files (< 3 entries)
+- Duplicate entries across pillars and categories
+- Break existing cross-references
+
+---
+
+## User Confirmation
+
+After consolidation, show the user:
+
+```markdown
+✅ Consolidation Complete!
+
+## Summary
+- **Learnings analyzed:** {N}
+- **Entries consolidated:** {M} → {K} generalized rules
+- **Pillars created:** {P}
+- **Total learnings:** {before} → {after}
+- **Reduction:** {percentage}%
+
+## Changes Made
+
+### Consolidated Patterns
+1. **{Pattern name}** - Combined {N} entries into 1 comprehensive rule
+   - File: `.sublation-os/memory/{category}-lessons.md`
+   - Entry: #{entry_number}
+
+### Pillar Organization
+1. **Work Pillar** - {N} learnings moved to `pillars/work-lessons.md`
+2. **HR Pillar** - {N} learnings moved to `pillars/hr-lessons.md`
+
+### Files Updated
+- `backend-lessons.md` - {N} entries consolidated, {M} moved
+- `frontend-lessons.md` - {N} entries consolidated
+- `index.md` - Updated with pillar links
+- Created: {N} new pillar files
+
+## Next Steps
+- Review consolidated entries for accuracy
+- Use `/sublation-os:recall {pattern}` to test searchability
+- Archive backups kept in `.sublation-os/memory/archive/{date}/`
+
+## Rollback
+If needed, restore from archives:
+```bash
+cp .sublation-os/memory/archive/{date}/*.bak .sublation-os/memory/
+```
+```
+
+---
+
+## Examples
+
+### Example: Consolidating Pagination Pattern
+
+**Before:**
+```markdown
+## Entry 5 - Backend
+Work service pagination uses Skip/Take at DB level
+
+## Entry 12 - Backend
+HR employee list uses IQueryable pagination
+
+## Entry 18 - Backend
+Finance reports paginate at query level
+```
+
+**After:**
+```markdown
+## Entry 25 - 2025-11-07 14:30 [CONSOLIDATED]
+
+### 🧠 Context
+Consolidated from entries #5, #12, #18. Multiple services implemented pagination patterns with similar approaches.
+
+### 📘 Lesson
+Always apply pagination at the database query level using IQueryable before materialization. This ensures only the required page is fetched, preventing memory issues with large datasets.
+
+### ⚙️ Application
+**General Guidelines:**
+1. Use IQueryable<T> in repository methods
+2. Apply Skip() and Take() before ToList()/ToArrayAsync()
+3. Add indexes on sorting columns
+4. Test with realistic data volumes (1000+ records)
+
+**Specific Applications:**
+- **Work Service:** WorkRepository.GetPagedWorkItems (line 145)
+- **HR Service:** EmployeeRepository.GetPagedEmployees (line 203)
+- **Finance Service:** ReportRepository.GetPagedReports (line 87)
+
+### 🧩 Examples
+
+**Example 1: Work Service**
+
+❌ **Anti-pattern:**
+```csharp
+var allWork = await _context.WorkItems.ToListAsync();
+return allWork.Skip(page * size).Take(size);
+```
+
+✅ **Correct:**
+```csharp
+return await _context.WorkItems
+    .OrderBy(w => w.CreatedAt)
+    .Skip(page * size)
+    .Take(size)
+    .ToListAsync();
+```
+
+**Example 2: HR Service**
+
+❌ **Anti-pattern:**
+```csharp
+var allEmployees = await _db.Employees.ToListAsync();
+return allEmployees.Skip(offset).Take(limit);
+```
+
+✅ **Correct:**
+```csharp
+return await _db.Employees
+    .Where(e => e.IsActive)
+    .OrderBy(e => e.LastName)
+    .Skip(offset)
+    .Take(limit)
+    .ToListAsync();
+```
+
+### 🏷️ Tags
+`#consolidated` `#performance` `#database` `#pagination` `#repository-pattern` `#WorkService` `#HRService` `#FinanceService`
+
+### 📎 Source Entries
+- Entry #5 from backend-lessons.md
+- Entry #12 from backend-lessons.md
+- Entry #18 from backend-lessons.md
+```
+
+### Example: Pillar Organization
+
+**Moving Work Service learnings to Work Pillar:**
+
+Create `.sublation-os/memory/pillars/work-lessons.md`:
+
+```markdown
+# Work Pillar Lessons
+
+This file contains learnings specific to the Work domain, including work items, assignments, tracking, and work service operations.
+
+**Pillar Components:**
+- Work Service
+- Work Repository
+- Work Item Domain Entities
+- Work Assignment Logic
+- Work Progress Tracking
+
+**Related Categories:**
+- See [Backend Lessons](../backend-lessons.md) for general backend patterns
+- See [Architecture Lessons](../architecture-lessons.md) for system design
+- See [Testing Lessons](../testing-lessons.md) for work service testing
+
+---
+
+## Entry 1 - 2025-11-07 14:35
+
+### 🧠 Context
+Work items require assignee validation before creation to prevent orphaned assignments.
+
+### 📘 Lesson
+Always validate that assignees exist and have proper permissions before creating work items in Work Service.
+
+### ⚙️ Application
+1. Check WorkService.CreateWorkItem (line 87) for validation pattern
+2. Use IUserRepository.ValidateAssignees() before work item creation
+3. Return specific error if assignee validation fails
+4. Log validation failures for audit trail
+
+### 🧩 Example
+
+❌ **Anti-pattern:**
+```csharp
+public async Task<WorkItem> CreateWorkItem(CreateWorkItemDto dto)
+{
+    var workItem = new WorkItem
+    {
+        AssigneeId = dto.AssigneeId // No validation!
+    };
+    return await _repo.CreateAsync(workItem);
+}
+```
+
+✅ **Correct:**
+```csharp
+public async Task<WorkItem> CreateWorkItem(CreateWorkItemDto dto)
+{
+    var assigneeValid = await _userRepo.ValidateAssignees(dto.AssigneeId);
+    if (!assigneeValid)
+    {
+        throw new ValidationException("Invalid assignee");
+    }
+
+    var workItem = new WorkItem
+    {
+        AssigneeId = dto.AssigneeId
+    };
+    return await _repo.CreateAsync(workItem);
+}
+```
+
+### 🏷️ Tags
+`#WorkService` `#validation` `#assignments` `#work-pillar`
+
+---
+```
+
+---
+
+## Advanced Features
+
+### Automatic Pattern Detection
+
+When analyzing learnings, look for:
+
+1. **Repeated service names** across multiple entries
+2. **Similar code patterns** in examples
+3. **Common tags** appearing together frequently
+4. **Related file references** in the same codebase area
+5. **Sequential learnings** about the same topic
+
+### Consolidation Metrics
+
+Track and report:
+- **Consolidation ratio:** entries before/after
+- **Pattern coverage:** how many examples per pattern
+- **Tag density:** average tags per entry
+- **Pillar distribution:** learnings per pillar
+- **File size reduction:** KB saved
+
+### Smart Suggestions
+
+Suggest consolidation when:
+- 3+ entries share 80%+ similar tags
+- Same file/class referenced in multiple entries
+- Similar anti-patterns appear in examples
+- Related lessons appear within 7 days of each other
+
+---
+
+## Notes
+
+- **Run monthly** or when memory files exceed 50 entries per category
+- **Backup first** - always create archives before consolidation
+- **User approval required** - show plan before executing
+- **Preserve traceability** - keep source entry references
+- **Maintain searchability** - consolidate tags, don't remove them
+
+---
+
+Happy consolidating! 🧹✨