Improvement

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

| 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 |
| A new report card over usage history | add-report |

## Workflow

```
┌─────────────────────────────────────────────────────────────┐
│  0. CHECK THE DESIGN (docs are the source of truth)          │
├─────────────────────────────────────────────────────────────┤
│  • Read USER_JOURNEYS, CANONICAL, TARGET, design.md          │
│  • Does the improvement change a law, an owner, a word?      │
│  • If so: write it into the docs, ask the user to confirm    │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼ (design confirmed, or unchanged)
┌─────────────────────────────────────────────────────────────┐
│  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                             │
└─────────────────────────────────────────────────────────────┘
```

## Phase 0: Check the design

The design docs are the source of truth ([AGENTS.md](../../../AGENTS.md#design-docs-are-the-source-of-truth)).
Read the design in order — [USER_JOURNEYS.md](../../../docs/architecture/USER_JOURNEYS.md),
[CANONICAL_MODEL.md](../../../docs/architecture/CANONICAL_MODEL.md), [TARGET_ARCHITECTURE.md](../../../docs/architecture/TARGET_ARCHITECTURE.md), then the
feature's `design.md`. An improvement that only makes the code match the docs needs no
approval. One that changes a law, its owner, a word the screen prints, or adds a piece is a
design change: write it into the docs and ask the user to confirm before coding.

## 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**: a mockup in `design-concept/<feature>/` first for a visible change,
then the real UI on mock data (`scripts/demo-screenshots.sh`) — never real names,
emails or usage. Views render and tell; a rule they need lives in the domain.

### 2. Domain Improvements

Enhance a rule on the type that owns it (CANONICAL §5) — tell, don't ask:

```
Examples:
- A status the view used to work out moves onto its owner
- A better status calculation
- Better encapsulation of an invariant
```

**Never** a new field on `UsageSnapshot`: the kernel is shrinking toward `Usage`
(CANONICAL §6). Put the rule on the value or aggregate that owns it.

**Test approach**: State-based tests on the owner

```swift
@Test func `should be critical when a tenth is left`() {
    let quota = UsageQuota(percentRemaining: 10, quotaType: .session, providerId: "claude")
    #expect(quota.status == .critical)
}
```

### 3. Data Source Improvements

Make fetching or reading usage better: a provider's definition, or a generic
worker in `DataSources` that every definition can use:

```
Examples:
- Better error messages (a `text` mapping's error phrases, a `UsageError` hint)
- More robust reading (a new JSON mapping rule instead of a script)
- Timeouts, `cache.ttl`, a remembered rate limit
- A fallback or hand-off (`fallback`, `fallbackOn`)
```

**Test approach**: golden tests that run the real definition over stubbed
connections (`StubbedProvider`), or worker tests in `Modules/DataSources/Tests/`.
Never a vendor-named Swift type: improve the definition, or the generic piece.

### 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)

Name each test `should <outcome> [when <situation>]`, in the person's words, never a method, type or mechanism verb → [Naming tests](../implement-feature/references/tdd-patterns.md#naming-tests).

### Write Test for Improved Behavior

```swift
@Suite
struct {Component}Tests {

    @Test func `should {improved outcome} [when {situation}]`() {
        // 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:

```bash
tuist test Providers         # one module's tests while working (schemes: Providers, DataSources, Domain, Infrastructure, AppTests, AcceptanceTests)
# tuist caches results; one suite for real, and the final check of everything:
xcodebuild test -workspace ClaudeBar.xcworkspace -scheme ClaudeBar-Workspace \
  -destination 'platform=macOS,arch=arm64' -only-testing:ProvidersTests/ClaudeAPITests
xcodebuild test -workspace ClaudeBar.xcworkspace -scheme ClaudeBar-Workspace -destination 'platform=macOS,arch=arm64'
```


## Architecture Reference

> **Reference:** [MODULAR_DESIGN.md](../../../docs/architecture/MODULAR_DESIGN.md) (modules) ·
> [TARGET_ARCHITECTURE.md](../../../docs/architecture/TARGET_ARCHITECTURE.md) (how a provider runs) ·
> [ARCHITECTURE.md](../../../docs/architecture/ARCHITECTURE.md) (the app layers)

Find which module the behaviour lives in before you change it: the table in
[implement-feature → Architecture](../implement-feature/SKILL.md#architecture) is the
one map (where each thing lives, and where its tests go).

A bug or improvement in a provider is made in its JSON (or its mapping
script), or generically in `DataSources` — never with vendor-named Swift, and
never with a line in `ClaudeBarApp` that names it (providers are found by
`ProviderCatalog.detect()`). Modules never `import Domain`.

## Guidelines

### Do

- Keep changes focused and minimal
- Maintain existing behavior
- Add tests for new behavior
- Follow existing code patterns
- Add the CHANGELOG line for a change the person notices

### 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
- [ ] Full `xcodebuild test` green (`tuist test` skips cached targets)
- [ ] Docs updated in the same change (feature or provider README / design.md)
- [ ] One line under `## [Unreleased]` in `CHANGELOG.md`, under its heading (`Fixed` / `Changed`): the effect in the person's words, ≤300 characters, an absolute issue or PR link, for a change the person notices