claude_memory 0.2.0 → 0.3.0

data/.claude/skills/quality-update/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: quality-update
+description: Incrementally implement code quality improvements from docs/quality_review.md with tests and atomic commits. Run after /review-for-quality to apply fixes.
+agent: general-purpose
+allowed-tools: Read, Grep, Edit, Write, Bash
+---
+
+# Quality Update - Incremental Implementation
+
+Systematically implement code quality improvements from the review document, making tested, atomic commits for each fix.
+
+## Process Overview
+
+1. **Read the quality review** from `docs/quality_review.md`
+2. **Prioritize improvements** (start with Quick Wins, then High Priority)
+3. **Implement fixes incrementally** (one logical change at a time)
+4. **Run tests after each change** to ensure nothing breaks
+5. **Make atomic commits** that capture the change and its purpose
+6. **Update review document** to track progress
+
+## Detailed Steps
+
+### Step 1: Read and Parse Review
+
+```bash
+# Read the current quality review
+Read docs/quality_review.md
+```
+
+Focus on these sections in priority order:
+1. **Appendix B: Quick Wins** - Start here (fast, low risk)
+2. **High Priority (This Week)** - Critical improvements
+3. **Medium Priority (Next Week)** - Important but not urgent
+4. Skip Low Priority items for now
+
+### Step 2: Select Next Improvement
+
+Choose improvements based on:
+- **Risk**: Low risk first (refactoring, style fixes)
+- **Dependencies**: Prerequisites before dependent work
+- **Atomicity**: Each commit should be one logical change
+- **Test coverage**: Ensure tests exist or add them
+
+### Step 3: Implement the Fix
+
+For each improvement:
+
+1. **Read affected files** to understand current state
+2. **Make the change** using Edit or Write
+3. **Run linter** to ensure style compliance:
+   ```bash
+   bundle exec rake standard:fix
+   ```
+4. **Run tests** to verify correctness:
+   ```bash
+   bundle exec rspec
+   ```
+5. **Fix any test failures** before proceeding
+
+### Step 4: Make Atomic Commit
+
+**Commit Message Format:**
+```
+[Quality] Brief description of what was fixed
+
+- Specific change made (e.g., "Extract DatabaseCheck from DoctorCommand")
+- Why this improves quality (e.g., "Improves SRP and testability")
+- Expert principle applied (e.g., "Sandi Metz: Single Responsibility")
+
+Addresses: docs/quality_review.md [section reference]
+```
+
+**Example Commit:**
+```bash
+git add -A
+git commit -m "[Quality] Fix public keyword placement in SQLiteStore
+
+- Move all public methods to top of class
+- Keep all private methods at bottom
+- Improves code readability and conventional Ruby structure
+
+Addresses: docs/quality_review.md (Jeremy Evans - Inconsistent Visibility)
+"
+```
+
+### Step 5: Document Progress
+
+After each successful commit:
+- Note which item was completed
+- Track how many items remain in current priority
+- Identify any blockers encountered
+
+### Step 6: Continue or Report
+
+**Continue** to next improvement if:
+- Tests pass ✅
+- Commit successful ✅
+- No blockers encountered ✅
+
+**Stop and report** if:
+- Tests fail after multiple fix attempts ❌
+- Change introduces unexpected complexity ❌
+- External dependency issue (gem version, etc.) ❌
+
+## Commit Strategy
+
+### Grouping Guidelines
+
+**✅ Good atomic commits:**
+- "Fix public keyword placement in SQLiteStore" (single file, style fix)
+- "Extract DatabaseCheck from DoctorCommand" (single responsibility extraction)
+- "Replace nil returns with NullExplanation in Recall" (consistent pattern)
+- "Consolidate ENV access via Configuration class" (centralize pattern)
+
+**❌ Too large (split these):**
+- "Refactor Recall class" (too broad - split into multiple commits)
+- "Fix all Sandi Metz violations" (too many changes at once)
+- "Update database and add tests" (should be separate commits)
+
+**❌ Too small (combine these):**
+- "Fix typo in comment" + "Fix another typo" (combine style fixes)
+- "Add space after comma" (use standard:fix instead)
+
+### When to Split Work
+
+Split into multiple commits when:
+- Touching multiple files that serve different purposes
+- Making structural change + adding tests (commit structure first, tests second)
+- Fixing multiple unrelated issues from review
+
+## Testing Requirements
+
+**Before each commit:**
+```bash
+# 1. Run linter
+bundle exec rake standard:fix
+
+# 2. Run full test suite
+bundle exec rspec
+
+# 3. Check for any warnings
+bundle exec rake
+```
+
+**If tests fail:**
+1. Fix the test failures first
+2. If fix is complex, it might need its own commit
+3. Never commit broken tests
+
+## Progress Tracking
+
+Keep a running count:
+- ✅ Quick Wins completed: X/Y
+- ✅ High Priority completed: X/Y
+- ⏳ Currently working on: [description]
+- ❌ Blocked: [description + reason]
+
+## Success Criteria
+
+The skill completes successfully when:
+- All Quick Wins from Appendix B are implemented ✅
+- Or at least 3-5 High Priority items are completed ✅
+- All tests pass ✅
+- All commits follow the format above ✅
+- Progress report provided ✅
+
+## Important Notes
+
+- **Never skip tests** - each change must pass tests before committing
+- **Keep commits focused** - one logical change per commit
+- **Use standard:fix** - auto-fix linting issues before committing
+- **Read before editing** - understand context before making changes
+- **Conservative approach** - if unsure about a change, skip it and report
+- **Track time** - if a fix takes > 30 minutes, it might need planning first
+
+## Example Session
+
+```
+1. Read docs/quality_review.md
+2. Start with Quick Win: "Fix public keyword placement in SQLiteStore"
+3. Read lib/claude_memory/store/sqlite_store.rb
+4. Move public methods to top, private to bottom
+5. Run: bundle exec rake standard:fix
+6. Run: bundle exec rspec
+7. Commit: "[Quality] Fix public keyword placement in SQLiteStore..."
+8. Next: "Consolidate ENV access via Configuration"
+9. [Continue process...]
+10. Report: "Completed 5/5 Quick Wins, started 2/6 High Priority items"
+```
+
+## Error Handling
+
+If you encounter issues:
+- **Test failures**: Debug and fix, or skip and report
+- **Merge conflicts**: Stop and report (user intervention needed)
+- **Missing dependencies**: Stop and report
+- **Unclear requirements**: Skip item and note in report
+
+## Final Report Format
+
+```
+## Quality Update Session Report
+
+### Completed ✅
+1. [Quick Win] Fixed public keyword placement in SQLiteStore (commit: abc123)
+2. [Quick Win] Consolidated ENV access via Configuration (commit: def456)
+3. [High Priority] Extracted BatchQueryBuilder from Recall (commit: ghi789)
+
+### In Progress ⏳
+- Working on: Extract DatabaseCheck from DoctorCommand
+- Status: 60% complete, tests passing
+
+### Blocked ❌
+- [High Priority] Split Recall.rb god object
+  - Reason: Requires architectural planning, too large for automated fix
+  - Recommendation: Run /review-for-quality again after completing other items
+
+### Summary
+- Quick Wins: 5/5 completed ✅
+- High Priority: 2/6 completed
+- Tests: All passing ✅
+- Commits: 5 atomic commits made
+- Time: ~2 hours
+
+### Next Steps
+1. Continue with remaining High Priority items
+2. Consider running /review-for-quality again to assess progress
+3. Plan architectural refactoring for Recall.rb god object
+```

data/.claude/skills/quality-update/implementation-guide.md

@@ -0,0 +1,346 @@
+# Implementation Guide for Quality Updates
+
+## Fix Categories & Approach
+
+### Category 1: Style & Convention Fixes (Low Risk)
+**Examples:**
+- Moving public/private method groups
+- Consistent method parentheses
+- Fixing attr_reader placement
+- Consolidating ENV access
+
+**Approach:**
+- Safe to do immediately
+- Run standard:fix after changes
+- Verify tests still pass
+- Commit individually
+
+### Category 2: Simple Refactoring (Low-Medium Risk)
+**Examples:**
+- Extract small methods from long methods
+- Rename for clarity
+- Remove duplicate code
+- Add guard clauses
+
+**Approach:**
+- Read surrounding code first
+- Make change incrementally
+- Run tests frequently
+- Commit when tests pass
+
+### Category 3: Structural Changes (Medium Risk)
+**Examples:**
+- Extract new classes
+- Introduce value objects
+- Add null objects
+- Create parameter objects
+
+**Approach:**
+- Plan the extraction first
+- Create new class/file
+- Move code incrementally
+- Update tests as you go
+- Commit the structure, then usage
+
+### Category 4: Database Changes (Medium-High Risk)
+**Examples:**
+- Migration framework changes
+- Schema modifications
+- DateTime conversions
+- Transaction additions
+
+**Approach:**
+- Test with backup database first
+- Ensure backward compatibility
+- Update tests for new behavior
+- May need multiple commits
+- Consider skipping and reporting if complex
+
+### Category 5: Architectural Changes (High Risk)
+**Examples:**
+- Splitting god objects (500+ lines)
+- Changing abstraction boundaries
+- Introducing new patterns
+- Major refactoring
+
+**Approach:**
+- **SKIP these** - too large for automated fixes
+- Report that they need manual planning
+- Suggest running /review-for-quality after other fixes
+- These need dedicated planning sessions
+
+## Prioritization Algorithm
+
+### Start with Quick Wins (Appendix B)
+1. Read all Quick Wins from docs/quality_review.md
+2. Sort by risk (lowest first)
+3. Implement in order
+4. Goal: Complete all Quick Wins in first pass
+
+### Move to High Priority Items
+1. Read all High Priority items
+2. Filter out Category 5 (Architectural) - skip these
+3. Sort remaining by:
+   - Risk (low to high)
+   - Dependencies (prerequisites first)
+   - Impact (high impact first if equal risk)
+4. Implement sorted list
+5. Goal: Complete 3-5 items before stopping
+
+### Skip Medium/Low Priority
+- Only tackle these if explicitly requested
+- Focus on Quick Wins + High Priority for automated fixes
+
+## Common Patterns & Solutions
+
+### Pattern: God Object (500+ lines)
+**Assessment:** Category 5 - Architectural
+**Action:** SKIP - Report that this needs manual planning
+**Reason:** Too complex for automated incremental fixes
+
+### Pattern: Duplicate Code (DRY violation)
+**Assessment:** Category 2 - Simple Refactoring
+**Action:** Extract to shared method/class
+**Steps:**
+1. Identify all occurrences
+2. Create extracted method/class
+3. Replace first occurrence
+4. Test
+5. Replace remaining occurrences
+6. Test
+7. Commit
+
+### Pattern: Nil Checks Everywhere
+**Assessment:** Category 3 - Structural (Null Object)
+**Action:** Introduce NullObject pattern
+**Steps:**
+1. Create NullObject class (e.g., NullFact)
+2. Implement required interface
+3. Replace `return nil` with `return NullFact.new`
+4. Remove nil checks in callers
+5. Test incrementally
+6. Commit structure first, then usage changes
+
+### Pattern: Raw SQL Instead of Sequel
+**Assessment:** Category 2 - Simple Refactoring
+**Action:** Replace with Sequel datasets
+**Steps:**
+1. Read the SQL query
+2. Translate to Sequel dataset methods
+3. Test the query returns same results
+4. Replace in code
+5. Test
+6. Commit
+
+### Pattern: Long Method (> 20 lines)
+**Assessment:** Category 2 - Simple Refactoring
+**Action:** Extract smaller methods
+**Steps:**
+1. Identify logical sections
+2. Extract one section to private method
+3. Name method clearly
+4. Test
+5. Commit
+6. Repeat for remaining sections
+
+### Pattern: Mixed I/O and Logic
+**Assessment:** Category 3-4 - Structural
+**Action:** Extract pure logic to separate method/class
+**Steps:**
+1. Identify pure logic (no I/O)
+2. Extract to separate method/class
+3. Pass data as parameters
+4. Call from original method
+5. Test both paths
+6. Commit
+
+## Decision Tree
+
+```
+Start with next item from review
+↓
+Is it Category 5 (Architectural)?
+├─ YES → SKIP, report as "needs planning"
+└─ NO → Continue
+    ↓
+    Does it have dependencies?
+    ├─ YES → Are dependencies complete?
+    │   ├─ NO → SKIP, note dependency
+    │   └─ YES → Continue
+    └─ NO → Continue
+        ↓
+        Can you understand the code?
+        ├─ NO → SKIP, report as "unclear"
+        └─ YES → Continue
+            ↓
+            Implement the fix
+            ↓
+            Run tests
+            ↓
+            Tests pass?
+            ├─ NO → Can fix in < 15 min?
+            │   ├─ YES → Fix and retry
+            │   └─ NO → SKIP, report as "complex"
+            └─ YES → Continue
+                ↓
+                Commit with quality message
+                ↓
+                Next item
+```
+
+## Time Budgets
+
+Set time limits to avoid getting stuck:
+
+- **Quick Win**: Max 15 minutes per item
+- **High Priority**: Max 30 minutes per item
+- **Debug test failure**: Max 15 minutes
+- **Understand code**: Max 10 minutes
+
+If time limit exceeded: SKIP and report reason
+
+## Testing Strategy
+
+### Test Frequency
+- After every file edit: Run relevant spec file
+- After every commit: Run full suite
+- If >5 files changed: Run full suite
+
+### Test Commands
+```bash
+# Single file
+bundle exec rspec spec/claude_memory/store/sqlite_store_spec.rb
+
+# Full suite
+bundle exec rspec
+
+# With linting
+bundle exec rake
+```
+
+### Test Failure Response
+1. Read error message carefully
+2. Check if your change caused it
+3. If yes: Fix the change
+4. If no: Might be pre-existing, note and continue
+5. If unsure: Revert change and skip item
+
+## Git Best Practices
+
+### Before Committing
+```bash
+# Check status
+git status
+
+# Review changes
+git diff
+
+# Stage specific files (not -A if unnecessary)
+git add lib/claude_memory/store/sqlite_store.rb
+
+# Or stage all if appropriate
+git add -A
+
+# Commit with quality message
+git commit -m "[Quality] ..."
+```
+
+### Commit Message Template
+```
+[Quality] <what was fixed in <50 chars>
+
+- <specific change>
+- <why this improves quality>
+- <expert principle>
+
+Addresses: docs/quality_review.md (<section>)
+```
+
+### After Committing
+```bash
+# Verify commit
+git log -1 --oneline
+
+# Continue to next item
+```
+
+## Red Flags - When to Stop
+
+Stop implementing and report if you encounter:
+- 🚩 Tests fail after 2 fix attempts
+- 🚩 Change requires modifying >10 files
+- 🚩 Change requires new gem dependencies
+- 🚩 Change touches critical path (authentication, data integrity)
+- 🚩 Unclear what the correct fix should be
+- 🚩 Time budget exceeded
+- 🚩 Git conflicts or merge issues
+
+## Success Metrics
+
+Good session results:
+- ✅ 5+ commits made
+- ✅ All tests passing
+- ✅ All Quick Wins completed
+- ✅ 3-5 High Priority items completed
+- ✅ Clear report of progress
+- ✅ No broken code left behind
+
+## Example Full Session
+
+```
+Session Start: 2026-01-26 10:00
+
+1. Read docs/quality_review.md
+   - Found 5 Quick Wins
+   - Found 6 High Priority items
+   - Plan: Complete all Quick Wins first
+
+2. Quick Win #1: Fix public keyword in SQLiteStore
+   - Read lib/claude_memory/store/sqlite_store.rb
+   - Moved public methods to top (lines 10-350)
+   - Moved private methods to bottom (lines 351-542)
+   - Run: bundle exec rspec spec/claude_memory/store/sqlite_store_spec.rb ✅
+   - Commit: [Quality] Fix public keyword placement... ✅
+
+3. Quick Win #2: Consolidate ENV access
+   - Read lib/claude_memory/configuration.rb
+   - Added global_db_path and project_db_path methods
+   - Updated 3 files to use Configuration
+   - Run: bundle exec rspec ✅
+   - Commit: [Quality] Consolidate ENV access via Configuration ✅
+
+4. Quick Win #3: Extract BatchQueryBuilder
+   - Created lib/claude_memory/recall/batch_query_builder.rb
+   - Extracted logic from batch_find_facts and batch_find_receipts
+   - Updated recall.rb to use new class
+   - Run: bundle exec rspec ✅
+   - Commit: [Quality] Extract BatchQueryBuilder from Recall ✅
+
+5. Quick Win #4: Fix boolean logic in option parsing
+   - Found in lib/claude_memory/commands/recall_command.rb
+   - Simplified double-negative logic
+   - Run: bundle exec rspec ✅
+   - Commit: [Quality] Simplify boolean logic in option parsing ✅
+
+6. Quick Win #5: Extract Formatter from MCP Tools
+   - Created lib/claude_memory/mcp/formatter.rb
+   - Moved formatting methods
+   - Updated tools.rb to use Formatter
+   - Run: bundle exec rspec ✅
+   - Commit: [Quality] Extract Formatter from MCP Tools ✅
+
+7. High Priority #1: Extract DatabaseCheck from DoctorCommand
+   - Started work...
+   - TIME LIMIT EXCEEDED (45 minutes)
+   - SKIP - Too complex, needs planning
+
+Session End: 2026-01-26 11:30
+Duration: 1.5 hours
+
+Results:
+- Quick Wins: 5/5 completed ✅
+- High Priority: 0/6 completed (1 attempted)
+- Commits: 5 atomic commits
+- Tests: All passing ✅
+- Issues: High Priority items need more planning time
+```