┌─────────────────────────────────────────────────────────────┐
│  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>/README.md if usage,        │
│    REST, or gotchas changed (flags: just run `make docs`)    │
│  • One CHANGELOG line under [Unreleased]                      │
│  • 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

Layer	Location	Improvement Examples
Domain	`Sources/Domain/`	New computed properties, convenience methods, better enums
Infrastructure	`Sources/Infrastructure/`	Better error mapping, additional field mapping
ASCCommand	`Sources/ASCCommand/`	Output formatting, command options, TUI enhancements

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>/README.md updated if usage, REST or gotchas changed; make docs if flags changed; one CHANGELOG line

Scenario	Skill to Use
Enhance existing behavior	improvement (this skill)
Add new feature	implement-feature

improvement

Improve asc-swift Feature

When to Use This vs Other Skills

Workflow