sublation-os 1.0.0 → 1.0.2

package/.claude/commands/sublation-os/review-v2.md

@@ -1,701 +0,0 @@
----
-argument-hint: [file-path or directory]
-description: Comprehensive code review using Chain of Thought analysis and ReAct investigation
----
-
-You are conducting a comprehensive code review using **Chain of Thought (CoT)** reasoning for systematic analysis and **ReAct** for investigating suspicious patterns.
-
-## Code to Review
-$message
-
----
-
-## Review Process
-
-### Phase 1: Understanding (Chain of Thought)
-
-Before identifying issues, deeply understand the code.
-
-**Think through these questions systematically:**
-
-1. **Purpose**: What is this code supposed to do?
-2. **Context**: How does it fit into the larger system?
-3. **Complexity**: What are the most complex parts?
-4. **Critical paths**: What are the high-risk areas?
-5. **Stakeholders**: Who uses or depends on this code?
-
-**Document your understanding:**
-```markdown
-## Code Understanding
-
-**Purpose**: {1-2 sentence summary}
-
-**Key Components**:
-- {Component 1}: {What it does}
-- {Component 2}: {What it does}
-
-**Critical Paths**:
-- {Path 1}: {Why it's critical}
-- {Path 2}: {Why it's critical}
-
-**Complexity Hotspots**:
-- {Location 1}: {Why it's complex}
-```
-
----
-
-### Phase 2: Load Context
-
-Before reviewing, load relevant context:
-
-#### User Standards
-Read applicable standards from `.sublation-os/standards/`:
-- For backend code: Read `backend/*.md`
-- For frontend code: Read `frontend/*.md`
-- For all code: Read `global/*.md`
-- For tests: Read `testing/*.md`
-
-#### Past Learnings
-Read relevant memory files from `.sublation-os/memory/`:
-- Start with `index.md` to identify relevant categories
-- Read category-specific lessons (backend/frontend/testing/architecture)
-- Look for:
-  - Known anti-patterns in this codebase
-  - Preferred patterns and conventions
-  - Security gotchas
-  - Performance lessons
-
----
-
-### Phase 3: Multi-Dimensional Analysis (Chain of Thought)
-
-Analyze the code across multiple dimensions. For each dimension, **think step by step** through potential issues.
-
-#### Dimension 1: Correctness 🎯
-
-**THINK**: Does this code do what it's supposed to do?
-
-Analyze systematically:
-- **Logic correctness**: Are conditions correct? Any off-by-one errors?
-- **Edge cases**: What happens with null, empty, or unexpected inputs?
-- **Error handling**: Are errors caught and handled appropriately?
-- **Data integrity**: Could data be corrupted or lost?
-- **Race conditions**: Any concurrency issues?
-
-**For each issue found, use ReAct to investigate:**
-
-**THOUGHT**: This loop condition looks suspicious - it might skip the last element
-
-**ACTION**: Check the loop boundaries and test with example values
-
-**OBSERVATION**: Confirmed - loop uses `<` instead of `<=`, missing last item
-
----
-
-#### Dimension 2: Security 🔒
-
-**THINK**: What could an attacker exploit?
-
-Use the STRIDE threat model:
-- **Spoofing**: Can authentication be bypassed?
-- **Tampering**: Can data be modified maliciously?
-- **Repudiation**: Can actions be denied?
-- **Information Disclosure**: Can sensitive data leak?
-- **Denial of Service**: Can the service be disrupted?
-- **Elevation of Privilege**: Can permissions be bypassed?
-
-**Common vulnerabilities to check:**
-- SQL Injection (unsanitized queries)
-- XSS (unescaped output)
-- CSRF (missing tokens)
-- Authentication bypass
-- Authorization flaws
-- Insecure dependencies
-- Hardcoded secrets
-- Path traversal
-- Command injection
-- Insecure deserialization
-
-**For each security concern:**
-
-**THOUGHT**: This SQL query uses string concatenation - potential SQL injection
-
-**ACTION**: Search codebase for the sanitization pattern used elsewhere
-
-**OBSERVATION**: Other queries use parameterized queries - this should too
-
----
-
-#### Dimension 3: Performance ⚡
-
-**THINK**: Where are the bottlenecks?
-
-Analyze systematically:
-- **Algorithmic complexity**: O(n²) where O(n) is possible?
-- **Database queries**: N+1 queries? Missing indexes?
-- **Caching**: Could results be cached?
-- **Memory usage**: Unnecessary allocations? Memory leaks?
-- **Network calls**: Too many API requests? Parallelizable?
-- **Blocking operations**: Synchronous where async would help?
-
-**For each performance issue:**
-
-**THOUGHT**: This loads all records into memory - could be 100k+ rows
-
-**ACTION**: Check if pagination or streaming is used elsewhere
-
-**OBSERVATION**: Similar endpoints use cursor pagination - apply here
-
----
-
-#### Dimension 4: Maintainability 🔧
-
-**THINK**: How hard is this to understand and modify?
-
-Evaluate:
-- **Readability**: Is the code clear? Are names descriptive?
-- **Complexity**: Are functions too long? Too many branches?
-- **Duplication**: Is code repeated unnecessarily?
-- **Documentation**: Are complex parts explained?
-- **Consistency**: Does it follow codebase conventions?
-- **Dependencies**: Are they necessary? Up to date?
-- **Technical debt**: What shortcuts were taken?
-
-**Apply codebase patterns:**
-
-**THOUGHT**: This function is 300 lines - violates the codebase pattern
-
-**ACTION**: Check past learnings for preferred function size
-
-**OBSERVATION**: Memory system shows 50-line limit with extraction pattern
-
----
-
-#### Dimension 5: Testing 🧪
-
-**THINK**: How testable is this code? What's the test coverage?
-
-Analyze:
-- **Testability**: Are dependencies injectable? Functions pure?
-- **Coverage**: Are critical paths tested?
-- **Test quality**: Do tests verify behavior or implementation?
-- **Edge cases**: Are error conditions tested?
-- **Brittleness**: Will tests break with minor refactoring?
-
-**Check against standards:**
-
-**THOUGHT**: No tests found for this critical business logic
-
-**ACTION**: Read testing standards to see requirements
-
-**OBSERVATION**: Standards require >80% coverage for services - needs tests
-
----
-
-#### Dimension 6: Architecture 🏗️
-
-**THINK**: Does this follow good design principles?
-
-Evaluate:
-- **SOLID principles**: Single responsibility, etc.
-- **Separation of concerns**: Are layers properly separated?
-- **Coupling**: Is code tightly coupled?
-- **Cohesion**: Do related things belong together?
-- **Patterns**: Are appropriate patterns used?
-- **Extensibility**: Easy to extend without modification?
-
-**Consider past learnings:**
-
-**THOUGHT**: This controller has database access - breaks layering
-
-**ACTION**: Check architecture lessons for preferred pattern
-
-**OBSERVATION**: Codebase uses repository pattern - should apply here
-
----
-
-#### Dimension 7: Standards Compliance 📋
-
-**THINK**: Does this follow the user's documented standards?
-
-Check against `.sublation-os/standards/`:
-- **Naming conventions**: Variables, functions, files
-- **Code style**: Indentation, formatting, structure
-- **Error handling**: Patterns used
-- **Validation**: Input validation approach
-- **API design**: REST conventions, response formats
-- **Component structure**: File organization
-
-**Flag violations:**
-
-**THOUGHT**: Error handling doesn't match standards
-
-**ACTION**: Read global/error-handling.md for requirements
-
-**OBSERVATION**: Standards require try-catch with structured logging - missing
-
----
-
-### Phase 4: Pattern Investigation (ReAct)
-
-For any suspicious patterns, investigate systematically:
-
-**Example:**
-
-**THOUGHT**: I see several async operations that could run in parallel but are sequential
-
-**ACTION**: Calculate potential time savings - 3 serial 100ms calls = 300ms
-
-**OBSERVATION**: Could reduce to 100ms with Promise.all() - significant improvement
-
-**THOUGHT**: Before recommending, check if there are dependencies between calls
-
-**ACTION**: Analyze data flow between the async operations
-
-**OBSERVATION**: No dependencies found - safe to parallelize
-
----
-
-## Review Report Structure
-
-Generate a comprehensive report following this structure:
-
-```markdown
-# Code Review Report
-
-**Reviewed**: {file paths}
-**Date**: {current date}
-**Reviewer**: review-v2 (AI-assisted)
-**Lines of Code**: {approximate count}
-
----
-
-## Executive Summary
-
-{2-3 sentence overview of code quality and key findings}
-
-**Overall Assessment**:
-- Correctness: ⭐⭐⭐⭐⭐ (5/5)
-- Security: ⭐⭐⭐⭐⬜ (4/5)
-- Performance: ⭐⭐⭐⬜⬜ (3/5)
-- Maintainability: ⭐⭐⭐⭐⬜ (4/5)
-- Testing: ⭐⭐⬜⬜⬜ (2/5)
-- Architecture: ⭐⭐⭐⭐⭐ (5/5)
-- Standards: ⭐⭐⭐⭐⬜ (4/5)
-
-**Recommendation**: ✅ Approve with changes | ⚠️ Needs significant work | ❌ Major issues
-
----
-
-## Critical Issues 🔴
-
-Issues that MUST be fixed before merging.
-
-### Issue 1: SQL Injection Vulnerability
-**Location**: `src/controllers/userController.js:45`
-**Severity**: 🔴 Critical - Security
-**Category**: Security - SQL Injection
-
-**Problem**:
-```javascript
-// ❌ CURRENT (Line 45)
-const query = `SELECT * FROM users WHERE id = ${userId}`;
-db.query(query);
-```
-
-**Why this is critical**:
-An attacker can inject SQL through the userId parameter, potentially accessing or deleting all database records.
-
-**Recommended fix**:
-```javascript
-// ✅ RECOMMENDED
-const query = 'SELECT * FROM users WHERE id = ?';
-db.query(query, [userId]);
-```
-
-**Reasoning**: Parameterized queries prevent SQL injection by treating input as data, not executable code. This pattern is used throughout the codebase (see src/models/User.js:23).
-
-**THOUGHT process**: Found string concatenation in SQL query → Checked if input is sanitized → Not sanitized → Checked codebase for correct pattern → Found parameterized query pattern.
-
----
-
-### Issue 2: {Next critical issue}
-{Repeat structure}
-
----
-
-## High Priority Issues 🟠
-
-Issues that should be fixed soon.
-
-### Issue 1: N+1 Query Problem
-**Location**: `src/services/orderService.js:78-85`
-**Severity**: 🟠 High - Performance
-**Category**: Performance - Database
-
-**Problem**:
-```javascript
-// ❌ CURRENT (Lines 78-85)
-const orders = await Order.findAll();
-for (const order of orders) {
-  order.items = await OrderItem.findByOrderId(order.id); // N queries
-}
-```
-
-**Impact**: With 1000 orders, this executes 1001 queries (1 + 1000). Response time: ~5-10 seconds.
-
-**Recommended fix**:
-```javascript
-// ✅ RECOMMENDED
-const orders = await Order.findAll({
-  include: [{
-    model: OrderItem,
-    as: 'items'
-  }]
-});
-```
-
-**Performance gain**: Reduces to 1 query. Expected response time: ~50-100ms (50-100x improvement).
-
-**Reasoning**: This ORM supports eager loading. Pattern used in src/services/productService.js:45. Past learnings (backend-lessons.md Entry 12) specifically flag N+1 queries as common problem.
-
-**Alternative solution**: Could use a single JOIN query if ORM isn't flexible enough, but ORM solution is cleaner.
-
----
-
-### Issue 2: {Next high priority issue}
-{Repeat structure}
-
----
-
-## Medium Priority Issues 🟡
-
-Issues that improve quality but aren't urgent.
-
-### Issue 1: Function Too Complex
-**Location**: `src/utils/validator.js:120-280`
-**Severity**: 🟡 Medium - Maintainability
-**Category**: Maintainability - Complexity
-
-**Problem**:
-- Function is 160 lines long
-- Cyclomatic complexity: ~25 (threshold: 10)
-- Difficult to test and understand
-
-**Reasoning**: This violates the codebase convention (past learnings show 50-line function limit) and makes future modifications risky.
-
-**Recommended refactoring**:
-```javascript
-// ✅ SPLIT INTO FOCUSED FUNCTIONS
-function validateUser(data) {
-  validateRequiredFields(data);
-  validateEmail(data.email);
-  validatePassword(data.password);
-  validateAge(data.age);
-  return true;
-}
-
-function validateRequiredFields(data) {
-  const required = ['email', 'password', 'name'];
-  for (const field of required) {
-    if (!data[field]) throw new Error(`${field} is required`);
-  }
-}
-```
-
-**Benefits**:
-- Each function has single responsibility
-- Easier to test individual validators
-- More reusable
-- Clearer intent
-
----
-
-## Low Priority Issues 🟢
-
-Nice-to-have improvements.
-
-### Issue 1: Inconsistent Naming
-**Location**: `src/components/UserProfile.jsx`
-**Severity**: 🟢 Low - Standards
-**Category**: Standards - Naming conventions
-
-**Problem**: Mix of camelCase and snake_case for variable names.
-
-**Current**: `user_name`, `userId`, `profile_data`
-**Standard**: All camelCase (per `standards/global/coding-style.md`)
-**Recommended**: `userName`, `userId`, `profileData`
-
----
-
-## Positive Observations ✅
-
-Things done well that should be maintained:
-
-1. **Excellent error handling** (lines 23-35): Comprehensive try-catch with structured logging
-2. **Good separation of concerns**: Controller → Service → Repository pattern followed
-3. **Clear naming**: Functions and variables have descriptive names
-4. **Type safety**: Good use of TypeScript types (if applicable)
-5. **Documentation**: Complex algorithms are well-commented
-
----
-
-## Standards Compliance Checklist
-
-Against `.sublation-os/standards/`:
-
-- ✅ **Coding style**: Follows indentation and formatting rules
-- ✅ **Naming conventions**: Mostly consistent (minor issues noted above)
-- ❌ **Error handling**: Missing structured logging in error paths
-- ✅ **API design**: RESTful conventions followed
-- ⚠️ **Testing**: Insufficient test coverage (45% vs 80% requirement)
-- ✅ **Documentation**: Adequate inline comments
-- ✅ **Validation**: Input validation present
-
----
-
-## Past Learnings Applied
-
-From `.sublation-os/memory/`:
-
-✅ **Applied**: Entry 8 (backend-lessons) - Used repository pattern correctly
-✅ **Applied**: Entry 15 (frontend-lessons) - Followed component composition pattern
-❌ **Missed**: Entry 12 (backend-lessons) - N+1 query antipattern present (flagged above)
-❌ **Missed**: Entry 23 (testing-lessons) - Missing edge case tests
-
----
-
-## Testing Gaps
-
-**Current coverage**: ~45% (estimated from test files)
-**Required coverage**: 80% (per `standards/testing/test-writing.md`)
-
-**Missing tests**:
-1. Edge case: Empty array input to `processOrders()`
-2. Error case: Network failure in API call
-3. Validation: Invalid email format handling
-4. Performance: Large dataset handling (1000+ items)
-
-**Recommended test additions**:
-```javascript
-// High priority test to add
-describe('processOrders edge cases', () => {
-  it('should handle empty order array', async () => {
-    const result = await processOrders([]);
-    expect(result).toEqual([]);
-  });
-
-  it('should handle API failure gracefully', async () => {
-    mockApi.get.mockRejectedValue(new Error('Network error'));
-    await expect(processOrders(validOrders))
-      .rejects.toThrow('Failed to process orders');
-  });
-});
-```
-
----
-
-## Architecture Assessment
-
-**Pattern analysis**:
-- ✅ **Layered architecture**: Clear separation (Controller/Service/Repository)
-- ✅ **Dependency injection**: Services injected, testable
-- ⚠️ **Single Responsibility**: Some functions do too much (noted above)
-- ✅ **DRY principle**: Minimal duplication
-- ❌ **Open/Closed**: Some classes hard to extend (tight coupling)
-
-**Recommendations**:
-1. Extract interface for OrderService to enable easier mocking
-2. Consider strategy pattern for different payment processors
-3. Use factory pattern for report generation (currently hardcoded)
-
----
-
-## Security Assessment
-
-**Vulnerabilities found**: 1 critical (SQL injection), 0 high, 2 medium
-
-**Security checklist**:
-- ❌ **Input validation**: Missing sanitization in userId parameter (CRITICAL)
-- ✅ **Authentication**: JWT properly verified
-- ✅ **Authorization**: Role checks present
-- ⚠️ **Data exposure**: Sensitive fields (password hash) returned in API response
-- ✅ **Dependencies**: No known vulnerabilities (checked npm audit)
-- ✅ **Secrets**: No hardcoded credentials
-- ✅ **HTTPS**: Enforced for all endpoints
-
----
-
-## Performance Assessment
-
-**Bottlenecks identified**:
-1. 🟠 N+1 query in order loading (~5s response time)
-2. 🟡 Synchronous file operations blocking event loop
-3. 🟡 Large payload (2MB) - no pagination
-
-**Performance recommendations**:
-1. Fix N+1 query (50-100x improvement)
-2. Use async file operations or worker threads
-3. Implement cursor pagination for large datasets
-4. Add caching for frequently accessed data (e.g., user profiles)
-
-**Estimated impact**: Fixing top 2 issues could reduce response time from ~6s to ~200ms.
-
----
-
-## Refactoring Opportunities
-
-**Technical debt identified**:
-
-1. **Extract utility functions**: Date formatting code repeated 5 times
-2. **Simplify complex conditionals**: Lines 145-180 have deeply nested if statements
-3. **Remove dead code**: Commented-out code at lines 200-220
-4. **Upgrade patterns**: Still using callbacks where async/await would be clearer
-
-**Priority**: Medium (not blocking, but improves maintainability)
-
----
-
-## Action Items
-
-### Must Do (Before Merge) 🔴
-1. [ ] Fix SQL injection vulnerability (Line 45)
-2. [ ] {Other critical issues}
-
-### Should Do (This Sprint) 🟠
-1. [ ] Fix N+1 query performance issue
-2. [ ] Add missing error handling with structured logging
-3. [ ] Increase test coverage to 80%
-
-### Nice to Have (Backlog) 🟡🟢
-1. [ ] Refactor complex validator function
-2. [ ] Standardize variable naming
-3. [ ] Add caching layer
-4. [ ] Extract repeated utility functions
-
----
-
-## Recommendations for Developer
-
-**Strengths to maintain**:
-- Good architectural layering
-- Clear naming and documentation
-- Proper use of design patterns
-
-**Areas for improvement**:
-- Security awareness (parameterized queries)
-- Performance optimization (database query patterns)
-- Test coverage (aim for 80%+)
-
-**Learning resources**:
-- SQL injection prevention: [OWASP guide]
-- N+1 queries: See `backend-lessons.md` Entry 12
-- Testing patterns: See `testing-lessons.md`
-
----
-
-## Next Review
-
-**When to review again**:
-- After critical issues are fixed
-- Before merging to main branch
-- After adding missing tests
-
-**Focus areas for next review**:
-- Verify security fixes
-- Validate performance improvements
-- Check test coverage increase
-
----
-
-## Appendix: Investigation Notes
-
-{Include any detailed ReAct investigation cycles that were particularly complex or instructive}
-
-### Investigation 1: SQL Injection Analysis
-
-**THOUGHT**: Saw string concatenation in SQL - potential injection
-
-**ACTION**: Checked if input is validated before query
-
-**OBSERVATION**: No validation found - direct concatenation
-
-**THOUGHT**: Need to confirm this is exploitable and find correct pattern
-
-**ACTION**: Checked similar queries in codebase
-
-**OBSERVATION**: All other queries use parameterized approach - this is the outlier
-
-**CONCLUSION**: Confirmed vulnerability, pattern for fix identified
-```
-
----
-
-## Quality Standards for Reviews
-
-### Excellent Review Characteristics
-
-✅ **Specific**: References exact file paths and line numbers
-✅ **Actionable**: Provides concrete code examples
-✅ **Reasoned**: Explains WHY something is an issue
-✅ **Contextual**: Considers codebase patterns and history
-✅ **Balanced**: Notes positive aspects, not just problems
-✅ **Prioritized**: Clear severity levels
-✅ **Evidence-based**: Uses ReAct to investigate before concluding
-
-### Poor Review Characteristics
-
-❌ **Vague**: "Code quality could be better"
-❌ **Unreasoned**: "This is wrong" without explanation
-❌ **Inconsistent**: Flags patterns that match codebase style
-❌ **Impractical**: Suggests major refactors without considering cost
-❌ **Unbalanced**: Only criticism, no recognition of good work
-
----
-
-## Post-Review Actions
-
-### Save Review Report
-Save to: `.sublation-os/reviews/[YYYY-MM-DD]-[file-or-feature-name]-review.md`
-
-### Suggest Learning Capture
-If notable issues found, suggest running `/learn` to capture:
-- New antipatterns discovered
-- Security vulnerabilities specific to this codebase
-- Performance patterns to avoid
-- Better approaches identified
-
-### Track Metrics (Optional)
-Consider tracking over time:
-- Average severity of issues found
-- Time to fix issues by severity
-- Recurring issue patterns
-- Test coverage trends
-
----
-
-## Integration Points
-
-**With `/investigate`**: If review finds bugs, use `/investigate` to diagnose root cause
-
-**With `/learn`**: Capture codebase-specific patterns discovered during review
-
-**With `implementer-v2`**: Review can inform implementation standards
-
-**With `.sublation-os/memory/`**: Check past learnings, add new ones
-
----
-
-## Summary
-
-This review command provides:
-- **7-dimensional analysis** (Correctness, Security, Performance, Maintainability, Testing, Architecture, Standards)
-- **Chain of Thought reasoning** for systematic evaluation
-- **ReAct investigation** for suspicious patterns
-- **Severity-based prioritization** with specific action items
-- **Integration with codebase knowledge** (standards + memory)
-- **Concrete, actionable recommendations** with code examples
-- **Balanced perspective** (positive + negative observations)
-- **Documentation** for future reference
-
-The goal is not just to find issues, but to **understand context**, **reason through trade-offs**, and **provide practical guidance** that improves code quality while respecting existing patterns and constraints.