---

name: improvement description: | Guide for making improvements to existing ClaudeBar functionality using TDD. Use this skill when: (1) Enhancing existing features (not adding new ones) (2) Improving UX, performance, or code quality (3) User asks "improve X", "make Y better", or "enhance Z" (4) Small enhancements that don't require full architecture design For NEW features, use implement-feature skill instead.

Improve ClaudeBar Feature

Make improvements to existing functionality using TDD and rich domain design.

When to Use This vs Other Skills

Workflow

Copy┌─────────────────────────────────────────────────────────────┐
│  1. UNDERSTAND CURRENT STATE                                 │
├─────────────────────────────────────────────────────────────┤
│  • Read existing code                                        │
│  • Understand current behavior                               │
│  • Identify what to improve                                  │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  2. WRITE TEST FOR IMPROVED BEHAVIOR (Red)                   │
├─────────────────────────────────────────────────────────────┤
│  • Test describes the IMPROVED behavior                      │
│  • Test should FAIL initially                                │
│  • Keep existing tests passing                               │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  3. IMPLEMENT & VERIFY (Green)                               │
├─────────────────────────────────────────────────────────────┤
│  • Implement the improvement                                 │
│  • New test PASSES                                           │
│  • All existing tests still pass                             │
└─────────────────────────────────────────────────────────────┘

Types of Improvements

1. UX Improvements

Enhance user experience without changing core logic:

CopyExamples:
- Settings view scrolls on small screens
- Better loading indicators
- Improved accessibility
- Cleaner visual layout

Test approach: UI behavior tests or manual verification

2. Domain Improvements

Enhance domain model behavior:

CopyExamples:
- Add computed property for common queries
- Improve status calculation
- Add convenience methods
- Better encapsulation

Test approach: State-based domain tests

Copy@Test func `model provides convenient access to lowest quota`() {
    // Given
    let snapshot = UsageSnapshot(quotas: [quota1, quota2, quota3])

    // Then - new convenience property
    #expect(snapshot.lowestQuota == quota2)
}

3. Infrastructure Improvements

Enhance probes, storage, or adapters:

CopyExamples:
- Better error messages
- More robust parsing
- Improved timeout handling
- Caching support

Test approach: Behavior tests with mocked dependencies

4. Performance Improvements

Optimize existing functionality:

CopyExamples:
- Reduce redundant API calls
- Lazy loading
- Parallel execution
- Caching

Test approach: Behavior tests (same results, better performance)

TDD Pattern (Chicago School)

Write Test for Improved Behavior

Copy@Suite
struct {Component}Tests {

    @Test func `{describes improved behavior}`() {
        // Given - standard setup
        let component = Component(...)

        // When - action
        let result = component.improvedMethod()

        // Then - verify improved behavior
        #expect(result.hasImprovedProperty)
    }
}

Keep Existing Tests

Improvements should NOT break existing behavior:

Copy# Run all tests to ensure no regressions
swift test

Architecture Reference

Full documentation: docs/ARCHITECTURE.md

Guidelines

Do

• Keep changes focused and minimal
• Maintain existing behavior
• Add tests for new behavior
• Follow existing code patterns
• Update CHANGELOG

Don't

• Over-engineer simple improvements
• Change unrelated code
• Break existing tests
• Add features (use implement-feature)
• Skip tests for "small" changes

Checklist

• Current behavior understood
• Improvement scope defined (minimal)
• Test for improved behavior written
• Test FAILS before implementation
• Improvement implemented
• New test PASSES
• All existing tests still pass (swift test)
• CHANGELOG updated with improvement