Improvement

Improve asc-swift Feature

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

When to Use This vs Other Skills

Workflow

┌─────────────────────────────────────────────────────────────┐
│  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                             │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  4. UPDATE FEATURE DOC (if public surface changed)           │
├─────────────────────────────────────────────────────────────┤
│  • Update docs/features/<feature>.md to match new behavior   │
│  • Only required when CLI flags, domain model fields,        │
│    affordances, or architecture changed                       │
│  • Derive from code — read files, then write                 │
└─────────────────────────────────────────────────────────────┘

Types of Improvements

1. Domain Model Improvements

Enhance value type behavior:

Examples:
- Add computed property for common queries (Build.isReady, App.shortIdentifier)
- Improve date formatting on Build.ageDescription
- Add convenience accessors on BetaGroup or BetaTester
- Better encapsulation of domain rules in ProcessingState

Test approach: State-based domain tests

@Test func `build provides human-readable processing state`() {
    let build = Build(id: "1", version: "2.0", processingState: .valid, uploadedDate: .now)
    #expect(build.processingState.displayName == "Valid")
}

2. Output Improvements

Enhance CLI output formatting:

Examples:
- Better table column widths or alignment
- Richer JSON output fields (switch formatItems → formatAgentItems for affordances)
- More useful error messages with suggestions
- Improved markdown formatting for apps/builds
- Add AffordanceProviding to existing model missing it

JSON output shape for agent-first commands: {"data":[{...fields..., "affordances":{...cmds...}}]} Use formatter.formatAgentItems() (not formatItems) for commands that should include affordances.

Test approach: OutputFormatterTests with known domain model inputs; affordance tests in AffordancesTests.swift

3. Infrastructure Improvements

Enhance OpenAPI adapters or error handling:

Examples:
- Better error messages from API failures
- Improved pagination handling
- More robust response field mapping
- Additional fields mapped from SDK types to domain types

Test approach: Adapter tests with mocked APIProvider

4. Command UX Improvements

Enhance CLI command ergonomics:

Examples:
- Better --help text
- Additional --filter or --sort options
- Smarter defaults for --limit
- Improved TUI navigation or display

Test approach: Argument parsing tests or manual TUI verification

TDD Pattern (Chicago School)

ALWAYS write tests first, then implement. Never write implementation code without a failing test. This is non-negotiable.

Think from the user's mental model — test cases describe what the user expects, not internal implementation details.

@Suite
struct {Component}Tests {
    // Name reflects user's expectation, not code internals
    @Test func `{what the user expects to see or happen}`() {
        // Given - standard setup
        let component = Component(...)

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

        // Then - verify improved state/return value
        #expect(result.hasImprovedProperty)
    }
}

Keep existing tests passing:

swift test  # Must remain all green

Architecture Reference

Guidelines

Do

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

Don't

• Write implementation before tests — always Red → Green → Refactor
• 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)
• docs/features/<feature>.md updated if CLI flags, domain model fields, affordances, or architecture changed