sublation-os 1.0.0

package/.claude/commands/sublation-os/investigate.md

@@ -0,0 +1,164 @@
+---
+argument-hint: [message]
+description: Diagnose errors using ReAct (Reasoning + Acting) methodology with iterative investigation
+---
+
+You are investigating an error using the **ReAct (Reasoning + Acting)** approach, which combines systematic reasoning with targeted actions to diagnose issues.
+
+## Error to Investigate
+$message
+
+---
+
+## Investigation Process
+
+Use the **Thought-Action-Observation** loop iteratively until the root cause is identified. Document each cycle clearly.
+
+### Investigation Cycle 1: Initial Analysis
+
+**THOUGHT**:
+Analyze the error systematically before taking action:
+- What does the error message tell me? (error type, location, context)
+- Based on the error type, what are the 3 most likely causes?
+- What information would help me confirm or eliminate these hypotheses?
+- What should I investigate first to get maximum diagnostic value?
+
+**ACTION**:
+{Describe what you're doing and why}
+Examples:
+- Read the file mentioned in the stack trace to understand context
+- Search for recent changes to the affected code
+- Check logs for related errors or warnings
+- Examine configuration files
+- Review related test files
+
+**OBSERVATION**:
+After completing the action, document what you learned:
+- What did I find? (specific findings, not interpretations)
+- Does this confirm or eliminate any hypotheses?
+- What new questions or patterns emerge?
+- Do I have enough information, or do I need another cycle?
+
+---
+
+### Investigation Cycle 2: Hypothesis Testing
+
+**THOUGHT**:
+Based on the previous observation, reason through the next step:
+- Which hypothesis is most likely now? Why?
+- What specific evidence would confirm or reject this hypothesis?
+- What's the next best action to take?
+
+**ACTION**:
+{Targeted investigation based on your reasoning}
+
+**OBSERVATION**:
+{What you discovered and how it changes your understanding}
+
+---
+
+### Investigation Cycle 3-N: Iterative Deep Dive
+
+**THOUGHT**: {Continue reasoning based on accumulated observations}
+**ACTION**: {Continue investigating}
+**OBSERVATION**: {Continue learning}
+
+*Continue cycles until you have high confidence in the root cause (typically 3-5 cycles)*
+
+---
+
+## Root Cause Analysis
+
+After completing investigation cycles, synthesize your findings:
+
+### 🎯 Root Cause
+{Clear, specific statement of what's wrong - reference exact files and line numbers if possible}
+
+### 🔍 Evidence Trail
+Document the key observations that led to this conclusion:
+1. {First key finding}
+2. {Second key finding}
+3. {Confirming evidence}
+
+### 📊 Confidence Level
+**Confidence**: ⬛⬛⬛⬜⬜ (High/Medium/Low)
+
+**Reasoning**: {Why are you confident or uncertain? What alternative explanations remain?}
+
+---
+
+## Resolution Plan
+
+### ✅ Recommended Fix
+
+**THOUGHT**:
+Given the root cause, what's the best approach to fix it?
+- Consider multiple solutions if applicable
+- Think through trade-offs and side effects
+- Evaluate complexity and risk
+
+**Primary Solution**:
+{Detailed fix with code examples or specific changes}
+
+**Why This Approach**:
+{Reasoning for why this is the best solution}
+
+**Alternative Solutions** (if applicable):
+{Other viable approaches and why they weren't chosen}
+
+### 🧪 Verification Steps
+How to confirm the fix works:
+1. {Specific test or check}
+2. {Expected outcome}
+3. {Additional validation}
+
+### ⚠️ Potential Side Effects
+{Any risks or areas to watch after applying the fix}
+
+---
+
+## Documentation
+
+Save this investigation report to:
+`.sublation-os/investigations/[YYYY-MM-DD]-[brief-description].md`
+
+Use this format for the filename:
+- `2025-01-15-auth-token-expiry.md`
+- `2025-01-15-database-connection-timeout.md`
+
+---
+
+## Quality Standards
+
+**Good Investigation Example**:
+
+**THOUGHT**: The error "Cannot read property 'map' of undefined" in UserList.tsx:45 suggests data isn't loaded. Most likely causes: (1) API call failed, (2) API returned unexpected format, (3) race condition in component mounting. I'll check the API call first since that's most common.
+
+**ACTION**: Read UserList.tsx to see how data is fetched and when map() is called.
+
+**OBSERVATION**: Line 45 calls users.map() but users comes from useState with no default value. The useEffect fetches users, but there's no loading state. The map() runs before data arrives.
+
+✅ **Specific and actionable**
+✅ **Clear reasoning documented**
+✅ **Each step builds on previous learning**
+
+**Poor Investigation Example**:
+
+**THOUGHT**: Something is wrong with the code.
+**ACTION**: Look at files.
+**OBSERVATION**: Found a problem.
+
+❌ **Too vague**
+❌ **No reasoning shown**
+❌ **Not helpful for learning**
+
+---
+
+## Integration with Memory System
+
+After resolving the issue, consider running `/learn` to capture:
+- The mistake or pattern that caused the issue
+- How to detect similar issues in the future
+- Codebase-specific gotchas discovered
+
+This helps future debugging sessions by building institutional knowledge.

package/.claude/commands/sublation-os/learn.md

@@ -0,0 +1,131 @@
+---
+description: Append a new learning entry to categorized memory files so it can be reloaded by the agent for future reasoning
+model: sonnet
+---
+
+You are capturing a learning moment from the current session to help future Claude sessions work more effectively on this codebase.
+
+## Your Task
+
+Analyze the recent conversation context and generate a structured learning entry. Focus on:
+
+1. **What went wrong or required correction** (if applicable)
+2. **What pattern or practice should be followed**
+3. **Codebase-specific insights** (architecture, conventions, gotchas)
+4. **Tool usage patterns** that worked well or should be avoided
+
+## Step 1: Determine Category
+
+First, determine which category this learning belongs to:
+
+- **backend** - APIs, databases, services, server-side logic, data access
+- **frontend** - UI components, state management, user interactions, styling
+- **testing** - Testing strategies, frameworks, mocking, test organization
+- **architecture** - System design, patterns, project structure, cross-cutting concerns
+- **general** - Workflow, tooling, debugging, anything that doesn't fit above
+
+The target file will be: `.sublation-os/memory/{category}-lessons.md`
+
+## Entry Format
+
+Generate the entry in this exact format:
+
+```markdown
+## Entry {N} - {YYYY-MM-DD HH:mm}
+
+### 🧠 Context
+{1-2 sentences: What happened? What was the task or correction?}
+
+### 📘 Lesson
+{Core principle or insight as a durable rule. Be specific to this codebase when possible.}
+
+### ⚙️ Application
+{How should this affect future reasoning? Be actionable and specific. Include:
+- Which files/services/patterns this applies to
+- What to check before making similar changes
+- What tools or approaches work best}
+
+### 🧩 Example
+{OPTIONAL: Concrete before/after or do/don't example}
+
+### 🏷️ Tags
+{Comma-separated tags for searchability: e.g., "Work service, bulk operations, async patterns, testing"}
+
+---
+
+```
+
+## Instructions
+
+1. **Read the existing file** (if it exists) to:
+   - Determine the next entry number
+   - Ensure consistent formatting
+   - Avoid duplicate lessons
+
+2. **Generate the entry** with:
+   - Current timestamp in format: YYYY-MM-DD HH:mm
+   - Specific references to files, services, or patterns
+   - Tags for easy searching (service names, patterns, concepts)
+
+3. **Append to file**: `.sublation-os/memory/{category}-lessons.md`
+   - The file should already exist with a template header
+   - Append the new entry at the end of the file
+   - Ensure proper spacing between entries
+
+4. **Update index** (optional): If adding significant new tags or this is a notable learning, you may update `.sublation-os/memory/index.md` to add the new tags to the tag index
+
+5. **Confirm to user**:
+   - Show the generated entry
+   - Mention the category, entry number, and file location
+   - Suggest when this learning might be relevant
+
+## File Header (if creating new file)
+
+```markdown
+# Learned Lessons
+
+This file contains durable learnings from Claude Code sessions to help future sessions work more effectively on this codebase.
+
+**Search tips:**
+- Use Ctrl+F to find specific services or patterns
+- Look for 🏷️ Tags sections to find related lessons
+- Entries are chronological - recent ones are at the bottom
+
+---
+
+```
+
+## Quality Standards
+
+- **Be specific**: "In Work service bulk operations, always use IWorkRepository.BulkUpdateAsync" not "Use async methods"
+- **Be actionable**: "Check WorkRepository.cs:245 for the pattern" not "Follow existing patterns"
+- **Be contextual**: Reference actual files, classes, methods when possible
+- **Be relevant**: Focus on lessons that will help future Claude sessions, not general programming advice
+
+## Examples of Good Lessons
+
+✅ "When adding new bulk operations to Work service, use BulkUpdate domain entity pattern (WorkRepository.cs:245-280) rather than individual update loops. Provides better performance and progress tracking."
+
+✅ "AR service uses legacy .NET Framework 4.8. Cannot use C# 9+ features like records or init-only properties. Check .csproj TargetFramework before suggesting modern syntax."
+
+✅ "Multi-tenant queries MUST include TenantPermaKey filter. Found missing in WorkRepository.GetWorkItems - caused cross-tenant data leak in testing."
+
+❌ "Use async/await for better performance" (too generic)
+❌ "Follow SOLID principles" (not actionable)
+❌ "Write tests" (not specific to this codebase)
+
+## After Writing
+
+Confirm to the user:
+```
+✅ Learning captured as Entry {N} in .sublation-os/memory/{category}-lessons.md
+
+Category: {category}
+This lesson will help future sessions with: {brief description}
+
+You can search for it using tags: {list key tags}
+```
+
+## Notes on Legacy File
+
+The original `learned-lessons.md` file is maintained for backward compatibility. New learnings should go to the categorized files, but you may still read the legacy file if it contains existing entries.

package/.claude/commands/sublation-os/optimise.md

@@ -0,0 +1,108 @@
+---
+description: Analyze this code for performance issues
+---
+
+# Performance Optimization Analysis
+
+You are a performance optimization specialist for .NET applications. Analyze the selected code or current context for performance issues and provide actionable recommendations.
+
+## Analysis Framework
+
+### 1. Identify Performance Issues
+Scan for these common .NET performance bottlenecks:
+
+**Database & ORM Issues:**
+- N+1 query problems (especially with NHibernate)
+- Missing indexes or inefficient queries
+- Large result sets without pagination
+- SELECT * queries instead of specific columns
+- Unnecessary database round-trips
+- Missing async/await for database operations
+
+**Memory & Resource Issues:**
+- Improper disposal of IDisposable resources
+- Large object allocations
+- String concatenation in loops (use StringBuilder)
+- Boxing/unboxing of value types
+- Memory leaks from event handlers or static references
+- Inefficient LINQ queries causing multiple enumerations
+
+**Concurrency & Threading:**
+- Blocking calls on async code (`.Result`, `.Wait()`)
+- Missing ConfigureAwait(false) in library code
+- Improper use of locks or synchronization
+- Thread pool starvation
+
+**Algorithm & Logic Issues:**
+- Inefficient algorithms (O(n²) when O(n) or O(log n) possible)
+- Unnecessary loops or iterations
+- Redundant computations
+- Missing caching for expensive operations
+
+**API & Network:**
+- Synchronous I/O operations
+- Chatty API calls (multiple calls when one would suffice)
+- Missing response compression
+- Large payloads without pagination
+
+### 2. Prioritize Issues
+Rank findings by:
+- **Impact**: High/Medium/Low performance impact
+- **Effort**: Easy/Medium/Hard to fix
+- **Risk**: Low/Medium/High risk of introducing bugs
+
+### 3. Provide Specific Recommendations
+For each issue found:
+1. **What**: Clearly describe the problem
+2. **Where**: Reference specific file and line numbers (file_path:line_number)
+3. **Why**: Explain the performance impact with estimated improvement if possible
+4. **How**: Provide concrete code examples showing before/after
+5. **Trade-offs**: Mention any downsides or considerations
+
+### 4. Optimization Techniques
+Consider these .NET-specific optimizations:
+- Use `Span<T>` and `Memory<T>` for memory-intensive operations
+- Leverage `ValueTask<T>` for frequently synchronous async methods
+- Apply `readonly struct` for immutable value types
+- Use `ArrayPool<T>` for temporary buffers
+- Implement proper async patterns throughout the call stack
+- Apply lazy initialization for expensive objects
+- Use compiled queries for repeated NHibernate/EF queries
+
+## Output Format
+
+Structure your analysis as:
+
+### 🔴 Critical Issues (Fix Immediately)
+- Issue description with file location
+- Performance impact and fix recommendation
+
+### 🟡 Significant Issues (Should Fix Soon)
+- Issue description with file location
+- Performance impact and fix recommendation
+
+### 🟢 Minor Improvements (Nice to Have)
+- Issue description with file location
+- Performance impact and fix recommendation
+
+### ✅ Good Practices Found
+- Highlight any exemplary performance patterns
+
+### 📊 Estimated Overall Impact
+- Provide realistic expectations for performance improvements
+
+## Context Awareness
+- Consider the BalancedLabs multi-tenant architecture
+- Account for NHibernate usage patterns
+- Consider IIS hosting implications
+- Be aware of SQL Server query optimization opportunities
+- Reference the CLAUDE.md performance considerations
+
+## Deliverables
+1. Prioritized list of issues with file locations
+2. Code snippets showing recommended changes
+3. Rationale for each recommendation
+4. Estimated performance impact
+5. Implementation difficulty assessment
+
+Begin your analysis now with the selected code or current file context.

package/.claude/commands/sublation-os/plan-product.md

@@ -0,0 +1,36 @@
+## Product Planning Process
+
+You are helping to plan and document the mission, roadmap and tech stack for the current product.  This will include:
+
+- **Gathering Information**: The user's product vision, user personas, problems and key features
+- **Mission Document**: Take what you've gathered and create a concise mission document
+- **Roadmap**: Create a phased development plan with prioritized features
+- **Tech stack**: Establish the technical stack used for all aspects of this product's codebase
+
+This process will create these files in `.sublation-os/product/` directory.
+
+### PHASE 1: Gather Product Requirements
+
+Use the **product-planner** subagent to create comprehensive product documentation.
+
+IF the user has provided any details in regards to the product idea, its purpose, features list, target users and any other details then provide those to the **product-planner** subagent.
+
+The product-planner will:
+- Confirm (or gather) product idea, features, target users, confirm the tech stack and gather other details
+- Create `.sublation-os/product/mission.md` with product vision and strategy
+- Create `.sublation-os/product/roadmap.md` with phased development plan
+- Create `.sublation-os/product/tech-stack.md` documenting all of this product's tech stack choices
+
+### PHASE 2: Inform the user
+
+After all steps are complete, output the following to inform the user:
+
+```
+Your product planning is all set!
+
+✅ Product mission: `.sublation-os/product/mission.md`
+✅ Product roadmap: `.sublation-os/product/roadmap.md`
+✅ Product tech stack: `.sublation-os/product/tech-stack.md`
+
+NEXT STEP 👉 Run `/shape-spec` or `/write-spec` to start work on a feature!
+```

package/.claude/commands/sublation-os/pr-description.md

@@ -0,0 +1,15 @@
+---
+description: Generate a pull request description
+---
+
+## Title
+{Summarize the PR with a clear, concise title}
+
+## What does this PR do?
+{Describe what this PR accomplishes from a product or user-facing perspective}
+
+## How does it do it?
+{Explain the key code or architectural changes that implement the solution}
+
+## Notes / Validation (optional)
+{Include any testing notes, known issues, or next steps if applicable}

package/.claude/commands/sublation-os/recall.md

@@ -0,0 +1,114 @@
+---
+description: Search across all memory files to find relevant learnings by keyword or tag
+model: haiku
+---
+
+You are helping the user search for relevant learnings in the Sublation-OS memory system.
+
+## Your Task
+
+Search across all memory files to find learnings that match the user's query. The user may search by:
+- **Keywords** - Any text that might appear in context, lesson, or application sections
+- **Tags** - Specific tags like `#performance`, `#database`, `#api`, etc.
+- **Category** - backend, frontend, testing, architecture, general
+
+## Memory File Locations
+
+Search in these files:
+- `.sublation-os/memory/backend-lessons.md`
+- `.sublation-os/memory/frontend-lessons.md`
+- `.sublation-os/memory/testing-lessons.md`
+- `.sublation-os/memory/architecture-lessons.md`
+- `.sublation-os/memory/general-lessons.md`
+- `.sublation-os/memory/learned-lessons.md` (legacy file for backward compatibility)
+
+## Instructions
+
+1. **Understand the query**: Analyze what the user is looking for
+   - If they mention a specific category, focus on that file first
+   - If they use a hashtag (e.g., `#performance`), search for tags
+   - Otherwise, search for keywords in all text content
+
+2. **Use Grep tool** to search across files:
+   - Use pattern matching for keywords or tags
+   - Search in all memory files unless user specified a category
+   - Use `-A` and `-B` flags to show context around matches
+
+3. **Present results**:
+   - Show entry number, date, and category for each match
+   - Display the relevant sections (Context, Lesson, Application)
+   - If many matches, show top 5 most relevant
+   - Include the file path for reference
+
+4. **Provide navigation**:
+   - Suggest related tags the user might want to search
+   - Mention how many total matches were found
+   - Offer to show more results if there are many
+
+## Example Search Patterns
+
+**Search by tag:**
+```
+User query: "performance"
+→ Use Grep with pattern: `#performance` or `performance` in all memory files
+```
+
+**Search by keyword:**
+```
+User query: "database queries"
+→ Use Grep with pattern: `database.*queries` or just `database` in all memory files
+```
+
+**Search by category:**
+```
+User query: "backend learnings about APIs"
+→ Focus on backend-lessons.md, search for `API` or `api`
+```
+
+## Output Format
+
+Present results like this:
+
+```
+🔍 Found {N} learning(s) matching "{query}":
+
+---
+
+**Entry {N} - {Category}** ({date})
+File: .sublation-os/memory/{category}-lessons.md
+
+### 🧠 Context
+{context text}
+
+### 📘 Lesson
+{lesson text}
+
+### ⚙️ Application
+{application text}
+
+### 🏷️ Tags
+{tags}
+
+---
+
+💡 Related tags you might want to search: {suggested tags}
+```
+
+## If No Results
+
+If no matches are found:
+```
+❌ No learnings found matching "{query}"
+
+Suggestions:
+- Try broader keywords
+- Check spelling and try synonyms
+- Browse categories: backend, frontend, testing, architecture, general
+- Use `/sublation-os:learn` to capture a new learning on this topic
+```
+
+## Additional Features
+
+- If user asks to "show more", display additional results beyond the first 5
+- If user wants to see a specific entry in full, read that file and show the complete entry
+- Suggest creating a new learning if the topic isn't well covered