Improvement

Improve ClaudeBar Feature

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

When to Use This vs Other Skills

Workflow

Copy code
┌─────────────────────────────────────────────────────────────┐
│  0. CHECK THE DESIGN (docs are the source of truth)          │
├─────────────────────────────────────────────────────────────┤
│  • Read USER_JOURNEYS, CANONICAL, TARGET, design.md          │
│  • Think the domain: how should it be? (domain-shape.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). Read the design in order — USER_JOURNEYS.md, CANONICAL_MODEL.md, 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.

Think the domain first. Before changing code, ask how the domain should be, from the person's problem rather than the class at hand. Ask the five questions of the types the improvement touches (would the person say it, does the thing decide about itself, can you see every state, is it as small as it can be, is what differs data) and refine them in the same change → domain-shape.md. An improvement is the usual moment to fit a type to its shape; a new aggregate or a moved owner is a design change, confirmed first.

Types of Improvements

1. UX Improvements

Enhance user experience without changing core logic:

Copy code
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:

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

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

Copy code
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:

Copy code
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.

Write Test for Improved Behavior

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

bashCopy code
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 (modules) · TARGET_ARCHITECTURE.md (how a provider runs) · ARCHITECTURE.md (the app layers)

Find which module the behaviour lives in before you change it: the table in implement-feature → 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
• Domain thought through: the touched types asked the five questions, refined in scope
• 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