improve

name	improve
description	Incrementally implement feature improvements from docs/improvements.md with tests and atomic commits. Focuses on new functionality rather than refactoring.
agent	general-purpose
allowed-tools	Read, Grep, Edit, Write, Bash
arguments	[{"name":"mode","description":"Execution mode: 'sub-agent' (default, sequential) or 'agent-team' (parallel via agent teams)","required":false,"default":"sub-agent"}]

Feature Improvements - Incremental Implementation

Systematically implement feature improvements from docs/improvements.md, making tested, atomic commits for each feature addition.

Execution Modes

This skill supports two modes, passed as the first argument:

• sub-agent (default): A single agent works through improvements sequentially. Best for small batches (1-3 features) or features with dependencies.
• agent-team: Spawns a coordinated team of agents that implement independent features in parallel. Best for larger batches (3+) of independent features.

---

Mode: agent-team

When invoked with agent-team, follow this process:

Step 1: Read and Assess Improvements

Read docs/improvements.md and identify all implementable features using the same feasibility criteria as sub-agent mode (skip Categories D-F, "Features to Avoid", "If Requested" items).

Step 2: Group Independent Features

Partition implementable features into independent groups:

• Features touching different files can be parallelized
• Features sharing files or with dependencies must be sequential
• Aim for 3-5 teammates maximum

Step 3: Create the Agent Team

Create an agent team. For each teammate:

1. Assign one or two related features per teammate
2. Provide full context — teammates don't share your conversation history
3. Include these instructions for each teammate:
   • Read relevant existing code before making changes
   • Follow the project's code style (Standard Ruby, frozen_string_literal)
   • Write tests for all new functionality
   • Run bundle exec rake standard:fix before committing
   • Run relevant spec file after each edit, full suite before committing
   • Run bundle exec rspec to verify all tests pass
   • Make atomic commits with [Feature] prefix format
   • Update docs/improvements.md to mark features as implemented
   • Reference .claude/skills/improve/feature-patterns.md for implementation recipes

Step 4: Monitor and Coordinate

• Wait for all teammates to complete their tasks
• If a teammate reports a blocker or conflict, help resolve it
• Do NOT implement tasks yourself — let teammates do the work

Step 5: Validate and Report

After all teammates finish:

1. Run the full test suite: bundle exec rspec
2. Run the linter: bundle exec rake standard:fix
3. If any failures, fix them or coordinate with the relevant teammate
4. Provide a consolidated progress report (same Final Report format as sub-agent mode)

---

Mode: sub-agent (default)

Process Overview

1. Check memory health by calling memory.check_setup to verify the system is operational
2. Read the improvements document from docs/improvements.md
3. Identify unimplemented features from "Remaining Tasks" section
4. Prioritize by stated priority (Medium → Low)
5. Assess feasibility (skip if too complex or requires external services)
6. Implement features incrementally (one logical feature at a time)
7. Run tests after each change to ensure nothing breaks
8. Make atomic commits that capture the feature and its purpose
9. Update improvements.md to mark features as implemented

Detailed Steps

Step 0: Verify Memory Health

Before starting, confirm the memory system is operational:

memory.check_setup

If status is not "healthy", address any issues before proceeding.

Step 1: Read and Parse Improvements Document

# Read the improvements document
Read docs/improvements.md

Focus on these sections:

1. Remaining Tasks - Unimplemented features
2. Medium Priority - Higher value features
3. Low Priority - Nice-to-have features
4. Features to Avoid - Do NOT implement these

Step 2: Prioritize Features

Priority Order:

1. Medium Priority items first
2. Low Priority items second
3. Skip items marked "If Requested" or "Features to Avoid"

Feasibility Assessment:

• ✅ Can implement: Pure Ruby, no external services, clear scope
• ⚠️ Consider carefully: Requires API integration, new dependencies
• ❌ Skip: Requires external services, architectural changes, unclear requirements

Step 3: Assess Each Feature

Before implementing, check:

✅ Safe to implement automatically:

• Small database schema additions (new columns, tables)
• New CLI commands with clear behavior
• Utility methods and helpers
• Enhanced output formatting
• Statistics and reporting features

⚠️ Implement with caution:

• Features requiring API calls (Claude API, external services)
• New gem dependencies (check compatibility first)
• Background processing (daemon/fork complexity)
• Features touching critical paths

❌ Skip and report:

• Web UI features (React, Sinatra, complex frontend)
• Worker service/daemon management
• Features requiring Python/Node.js
• Vector database integration (ChromaDB, external services)
• Health monitoring (unless simple)

Step 4: Implement the Feature

For each feature:

1. Read relevant code to understand where feature fits
2. Plan the implementation:
   • Which files need changes?
   • What tests are needed?
   • Are there dependencies?
3. Implement incrementally:
   • Schema changes first (if needed)
   • Core functionality
   • CLI command (if applicable)
   • Tests
4. Run linter:

   bundle exec rake standard:fix
   

5. Run targeted tests after each edit:

   bundle exec rspec spec/claude_memory/<relevant_spec>.rb
   

6. Run full suite before committing:

   bundle exec rspec
   

7. Fix any test failures before proceeding

Step 5: Make Atomic Commit

Commit Message Format:

[Feature] Brief description of what was added

- Specific implementation details
- Why this improves the system
- Reference to docs/improvements.md section

Implements: docs/improvements.md (Section: <name>)

Example Commit:

git add -A
git commit -m "[Feature] Add ROI metrics tracking for distillation

- Add ingestion_metrics table with token counts
- Track input_tokens, output_tokens, facts_extracted
- Add metrics display to stats command
- Show efficiency (facts per 1k tokens)

Implements: docs/improvements.md (Section: ROI Metrics and Token Economics)
"

Step 6: Update improvements.md

After successful implementation:

1. Move item to "Implemented Improvements" section
2. Add date and brief description
3. Update "Remaining Tasks" to remove completed item
4. Commit the documentation update:

   git add docs/improvements.md
   git commit -m "[Docs] Mark <feature> as implemented"
   

Step 7: Continue or Report

Continue to next feature if:

• Tests pass ✅
• Commit successful ✅
• Feature works as expected ✅
• No blockers encountered ✅

Stop and report if:

• Tests fail after multiple fix attempts ❌
• Feature requires external services ❌
• Complexity exceeds estimate ❌
• Unclear requirements ❌
• Time budget exceeded ❌

Feature Categories & Approach

Category A: Schema Additions (Low Risk)

Examples:

• Add metrics table
• Add columns for metadata
• Add indexes

Approach:

• Schema version bump
• Migration method
• Tests for new schema
• Single commit

Category B: Statistics & Reporting (Low Risk)

Examples:

• Enhanced stats command
• ROI metrics display
• Better formatting

Approach:

• Query implementation
• Output formatting
• Tests for accuracy
• Single commit

Category C: CLI Commands (Low-Medium Risk)

Examples:

• New commands (embed, stats enhancements)
• Command options

Approach:

• Command class
• Registry update
• Tests for command
• Help documentation
• Single commit

Category D: Background Processing (Medium Risk)

Examples:

• Async hook execution
• Fork/daemon processes

Approach:

• ASSESS CAREFULLY - fork/daemon in Ruby is tricky
• Consider simple async approach first
• Test on multiple platforms
• May need multiple commits
• May skip if too complex

Category E: External Integration (Medium-High Risk)

Examples:

• API calls (Claude, external services)
• New gem dependencies
• External tool integration

Approach:

• ASSESS CAREFULLY - adds dependencies
• Check gem compatibility
• Error handling critical
• May need API keys
• Consider skipping if complex

Category F: Architectural Changes (High Risk)

Examples:

• Worker services
• Web UI
• New database systems

Approach:

• SKIP - too complex for automated implementation
• Report as "needs planning"
• These require design sessions

Implementation Examples

Example 1: ROI Metrics (Medium Priority)

Assessment: Category A + B (Schema + Reporting) - Safe to implement

Steps:

1. Add migration for ingestion_metrics table
2. Add tracking in distiller (if implemented) or stub for future
3. Add aggregation query methods
4. Enhance stats command to display metrics
5. Add tests
6. Commit
7. Update improvements.md

Time Estimate: 30-45 minutes

Example 2: Background Processing (Medium Priority)

Assessment: Category D (Background) - Medium risk

Steps:

1. Research Ruby async options (Process.fork vs Thread)
2. Add --async flag to hook commands
3. Simple fork approach (not full daemon)
4. Output logging
5. Tests on Unix systems (may skip Windows)
6. Commit
7. Update improvements.md

Time Estimate: 45-60 minutes Risk: May skip if too complex

Example 3: Web UI (Low Priority, "If Requested")

Assessment: Category F (Architectural) - High risk

Action: SKIP - Too complex, marked "if requested" Report: "Web UI requires design session, skipped per priority guidance"

Decision Tree

Read next feature from improvements.md
↓
Is it marked "Features to Avoid"?
├─ YES → SKIP completely
└─ NO → Continue
    ↓
    Is it marked "If Requested"?
    ├─ YES → SKIP, note as "needs user request"
    └─ NO → Continue
        ↓
        Assess category (A-F)
        ↓
        Category F (Architectural)?
        ├─ YES → SKIP, report as "needs planning"
        └─ NO → Continue
            ↓
            Category E (External)?
            ├─ YES → Assess carefully, may skip
            └─ NO → Continue
                ↓
                Category D (Background)?
                ├─ YES → Assess carefully, may skip
                └─ NO → Continue
                    ↓
                    Does it have dependencies on other features?
                    ├─ YES → Are dependencies complete?
                    │   ├─ NO → SKIP, note dependency
                    │   └─ YES → Continue
                    └─ NO → Implement (Categories A-C safe)
                        ↓
                        Implement the feature
                    ↓
                    Run tests
                    ↓
                    Tests pass?
                    ├─ NO → Can fix in < 20 min?
                    │   ├─ YES → Fix and retry
                    │   └─ NO → SKIP, report as "complex"
                    └─ YES → Continue
                        ↓
                        Commit with [Feature] message
                        ↓
                        Update improvements.md
                        ↓
                        Commit documentation update
                        ↓
                        Next feature

Time Budgets

Per Feature:

• Category A (Schema): Max 15 minutes — skip if stuck after 15
• Category B (Reporting): Max 20 minutes — skip if stuck after 20
• Category C (CLI): Max 30 minutes — skip if stuck after 30
• Category D (Background): Max 45 minutes (or skip at first sign of daemon complexity)
• Category E (External): Max 30 minutes (or skip at first sign of dependency issues)

Per Debug Cycle:

• Test failure fix: Max 15 minutes — if you can't fix it in 15 minutes, revert and skip
• Understanding code: Max 10 minutes — if unclear after 10 minutes, skip and report

Session Total: Max 2 hours

If time budget exceeded: SKIP remaining features and report.

Testing Strategy

Test Frequency

• After each file edit: Run the relevant spec file
• After schema changes: Run spec/claude_memory/store/
• After new command: Run spec/claude_memory/commands/
• Before each commit: Full test suite
• If >5 files changed: Full test suite immediately

Test Commands

# Single relevant spec (fastest feedback)
bundle exec rspec spec/claude_memory/commands/metrics_command_spec.rb

# Module-level specs
bundle exec rspec spec/claude_memory/commands/
bundle exec rspec spec/claude_memory/store/

# Full suite (before commit)
bundle exec rspec

# With linting (final check)
bundle exec rake

Test Failure Response

1. Read error message carefully
2. Check if your change caused it (vs pre-existing)
3. If your change: fix within 15 minutes or revert and skip
4. If pre-existing: note and continue
5. If unsure: revert change and skip item

New Feature Tests

Always add tests for new features:

# spec/claude_memory/commands/new_feature_spec.rb
RSpec.describe ClaudeMemory::Commands::NewFeature do
  it "implements the feature correctly" do
    # Test implementation
  end

  it "handles errors gracefully" do
    # Test error cases
  end
end

Documentation Updates

After Each Implementation

Update docs/improvements.md:

1. Move to Implemented section:

   ## Implemented Improvements ✓
   
   14. **ROI Metrics Tracking** - ingestion_metrics table, stats display
   

2. Remove from Remaining Tasks:

   ### Remaining Tasks
   
   - [x] ROI metrics table for token tracking during distillation
   - [ ] Background processing (--async flag for hooks)
   

3. Update last modified date:

   *Last updated: 2026-01-26 - Added ROI metrics tracking*
   

Progress Tracking

Keep running count:

• ✅ Medium Priority completed: X/Y
• ✅ Low Priority completed: X/Y
• ⏳ Currently working on: [feature name]
• ⚠️ Skipped (complex): [list]
• ❌ Blocked: [list with reasons]

Success Criteria

Session completes successfully when:

• At least 2-3 Medium Priority features implemented ✅
• All tests pass ✅
• All commits follow [Feature] format ✅
• docs/improvements.md updated ✅
• Progress report provided ✅

Important Notes

• Never skip tests - each feature must pass tests before committing
• Stay conservative - skip complex features, report them
• One feature at a time - don't combine unrelated features
• Update documentation - mark features as implemented
• Read before coding - understand existing code first
• Check dependencies - verify gems are compatible
• Test incrementally - after each logical step

Red Flags - When to Skip

Skip feature and report if you encounter:

• 🚩 Requires external services (ChromaDB, web servers, etc.)
• 🚩 Needs background daemon/worker
• 🚩 Requires new major dependencies
• 🚩 Touches security-critical code
• 🚩 Unclear requirements or scope
• 🚩 Time budget exceeded
• 🚩 Marked "Features to Avoid"
• 🚩 Marked "If Requested" or "Only if users request"
• 🚩 Tests fail after 2 fix attempts

Example Session

Session Start: 2026-01-26 14:00

1. Read docs/improvements.md
   - Found 4 Remaining Tasks
   - 2 Medium Priority, 2 Low Priority
   - Plan: Start with Medium Priority

2. Medium Priority #1: Background Processing (--async flag)
   - Category: D (Background)
   - Assessment: Medium risk, daemon complexity
   - TIME ESTIMATE: 60 minutes
   - DECISION: SKIP - Too complex, needs design
   - Reason: Ruby daemon management is tricky, fork approach needs careful testing

3. Medium Priority #2: ROI Metrics Tracking
   - Category: A + B (Schema + Reporting)
   - Assessment: Low risk
   - Implement:
     a. Add schema migration v7
     b. Add ingestion_metrics table
     c. Add aggregate_metrics method to store
     d. Enhance stats command
     e. Add tests
   - Run: bundle exec rspec ✅
   - Commit: [Feature] Add ROI metrics tracking... ✅
   - Update: docs/improvements.md ✅
   - Commit: [Docs] Mark ROI metrics as implemented ✅

4. Low Priority #1: Structured Logging
   - Category: C (CLI)
   - Assessment: Low risk
   - Implement:
     a. Add Logger configuration
     b. Add JSON formatter
     c. Add log output to commands
     d. Add --log-level flag
     e. Add tests
   - Run: bundle exec rspec ✅
   - Commit: [Feature] Add structured logging... ✅
   - Update: docs/improvements.md ✅
   - Commit: [Docs] Mark structured logging as implemented ✅

5. Low Priority #2: Embed Command
   - Category: C (CLI)
   - Started implementation...
   - TIME LIMIT EXCEEDED (45 minutes)
   - SKIP - More complex than expected

Session End: 2026-01-26 15:30
Duration: 1.5 hours

Results:
- Medium Priority: 1/2 completed (1 skipped - too complex)
- Low Priority: 1/2 completed (1 time exceeded)
- Commits: 4 (2 feature, 2 docs)
- Tests: All passing ✅
- Features added: ROI metrics, Structured logging

Final Report Format

## Feature Implementation Session Report

### Completed ✅
1. [Medium] ROI Metrics Tracking (commit: abc123)
   - Added ingestion_metrics table
   - Enhanced stats command
   - Shows token efficiency metrics

2. [Low] Structured Logging (commit: def456)
   - JSON log formatter
   - --log-level flag for commands
   - Better debugging visibility

### Skipped ⚠️
- [Medium] Background Processing (--async flag)
  - Reason: Ruby daemon complexity, needs design session
  - Recommendation: Plan this separately with forking strategy

- [Low] Embed Command
  - Reason: Time budget exceeded (45 min)
  - Progress: 60% complete, needs embedding generation logic
  - Recommendation: Complete in focused session

### Summary
- Medium Priority: 1/2 completed (50%)
- Low Priority: 1/2 completed (50%)
- Tests: All passing ✅
- Commits: 4 total (2 features + 2 docs)
- Time: 1.5 hours

### Next Steps
1. Design session for background processing
2. Complete embed command implementation
3. Consider remaining Low Priority items
4. Run /review-for-quality to assess any code quality issues from new features