┌─────────────────────────────────────────────────────────────┐
│  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:

Examples:
- 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:

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

Test approach: State-based domain tests

@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:

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

Test approach: Behavior tests with mocked dependencies

4. Performance Improvements

Optimize existing functionality:

Examples:
- 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

@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:

# Run all tests to ensure no regressions
swift test

Architecture Reference

Full documentation: docs/ARCHITECTURE.md

Layer	Location	Improvement Examples
Domain	`Sources/Domain/`	New computed properties, convenience methods
Infrastructure	`Sources/Infrastructure/`	Better parsing, error handling
App	`Sources/App/`	UI enhancements, accessibility

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

Scenario	Skill to Use
Enhance existing behavior	improvement (this skill)
Fix broken behavior	fix-bug
Add new feature	implement-feature
Add new AI provider	add-provider

improvement

Improve ClaudeBar Feature

When to Use This vs Other Skills

Workflow