name: state-management description: Cache management, configuration best practices, and progressive disclosure patterns for efficient context window usage. Use when working with large responses, optimizing token costs, or managing plugin state across operations. version: 0.0.1 token_cost: ~40

State Management Skill

Optimizing token efficiency and state management in xc-plugin

Overview

The xc-plugin implements sophisticated state management through caching, progressive disclosure, and configuration management. This Skill teaches how to leverage these patterns to minimize token usage, improve performance, and maintain clean state across operations.

Key Benefits:

85-90% token reduction through progressive disclosure
Cache-friendly operations avoid redundant work
Deterministic state ensures reliable test results
Configuration consistency across development workflows

When to Use This Skill

Use this Skill when you need to:

Optimize Token Usage
- Working with large device lists or build logs
- Reducing context window consumption
- Implementing efficient query patterns
Manage Cache State
- Understanding when responses are cached
- Invalidating stale cache entries
- Querying cached data efficiently
Handle Configuration
- Setting up consistent build environments
- Managing simulator preferences
- Configuring test execution parameters
Design Efficient Workflows
- Implementing progressive disclosure patterns
- Avoiding expensive repeated operations
- Building cache-aware automation

Key Concepts

Progressive Disclosure Pattern

Principle: Show essentials first, provide details on-demand.

Instead of returning massive datasets that consume tokens, xc-plugin returns:

Summary - Key metrics and booted devices (~100 tokens)
cache_id - Reference to full dataset
Follow-up query - Retrieve complete details only if needed

Token Efficiency:

Traditional approach: 2000 tokens (full device list)
Progressive disclosure: 100 tokens (summary) + optional 2000 tokens (details)
Average savings: 95% (most queries don't need full details)

Cache Architecture

The plugin uses deterministic caching for expensive operations:

Cache Key Generation:

SHA-256 hash of operation + parameters
First 16 characters used as cache_id
Deterministic: Same input → Same cache_id

Cache Storage:

In-memory for current session
Optional disk persistence
Automatic expiration (configurable TTL)

Cache-Friendly Operations:

list operations (device lists, app lists)
build operations (build logs, test results)
describe operations (accessibility trees)

Response Types

SuccessResult with Progressive Disclosure:

{
  success: true,
  data: {
    summary: "31 devices available, 1 booted",
    booted_devices: [...],
    cache_id: "a1b2c3d4e5f6g7h8"
  },
  summary: "Device list retrieved successfully"
}

Follow-up Query Pattern:

{
  operation: "get-details",
  cache_id: "a1b2c3d4e5f6g7h8",
  detail_type: "full-list"
}

Workflows

Workflow 1: Cache-Aware Device Listing

Initial Query (Token-Efficient):

{
  "operation": "list",
  "parameters": {
    "concise": true
  }
}

Response:

{
  "success": true,
  "data": {
    "summary": {
      "total_devices": 47,
      "available_devices": 31,
      "booted_devices": 1
    },
    "booted": [
      {
        "name": "iPhone 15",
        "udid": "ABC123...",
        "state": "Booted",
        "runtime": "iOS 17.0"
      }
    ],
    "cache_id": "sim-list-xyz789"
  }
}

Follow-Up (Only If Needed):

{
  "operation": "get-details",
  "cache_id": "sim-list-xyz789",
  "detail_type": "full-list"
}

Token Analysis:

Initial query: ~150 tokens
Follow-up (if needed): ~2000 tokens
Traditional approach: ~2000 tokens always
Savings: 92% when details not needed

Workflow 2: Build Cache Management

Build Operation:

{
  "operation": "build",
  "scheme": "MyApp",
  "configuration": "Debug",
  "output_format": "summary"
}

Response with Cache:

{
  "success": true,
  "data": {
    "message": "Build succeeded",
    "build_time": "45.2s",
    "warnings": 3,
    "cache_id": "build-abc123"
  },
  "summary": "Build completed successfully with 3 warnings"
}

Retrieve Full Logs:

{
  "operation": "get-details",
  "cache_id": "build-abc123",
  "detail_type": "full-log"
}

Cache Invalidation Scenarios:

Source code changes
Scheme configuration changes
Clean operation executed
Manual cache clear

Workflow 3: Configuration State Management

Query Current Configuration:

{
  "operation": "cache",
  "sub_operation": "get-config"
}

Response:

{
  "cache_enabled": true,
  "cache_ttl": 3600,
  "max_cache_size": 100,
  "persistence_enabled": false
}

Update Configuration:

{
  "operation": "cache",
  "sub_operation": "set-config",
  "parameters": {
    "cache_ttl": 7200,
    "persistence_enabled": true
  }
}

Workflow 4: State Cleanup Between Tests

Pattern for Clean Test State:

1. cache (clear: "all") → Remove all cached data
2. device-lifecycle (erase) → Reset simulator state
3. app-lifecycle (uninstall) → Remove app
4. app-lifecycle (install) → Fresh install
5. app-lifecycle (launch) → Start with clean state
6. (run tests) → Execute test suite
7. cache (clear: "response") → Clean response cache

Why This Matters:

Eliminates test interdependencies
Prevents cache poisoning
Ensures reproducible results
Catches state-dependent bugs

Progressive Disclosure Pattern

Pattern Structure

Level 1: Summary (Always Returned)

{
  "summary": {
    "key_metric_1": "value",
    "key_metric_2": "value",
    "action_taken": "description"
  },
  "cache_id": "unique-identifier",
  "next_steps": [
    "Suggested action 1",
    "Suggested action 2"
  ]
}

Level 2: Detailed Query (On-Demand)

{
  "operation": "get-details",
  "cache_id": "unique-identifier",
  "detail_type": "full-data|errors-only|warnings-only|metadata"
}

When to Use Progressive Disclosure

Always Use For:

Device lists (>5 devices)
Build logs (>100 lines)
Test results (>10 tests)
Accessibility trees (>20 elements)
App lists (>10 apps)

Skip For:

Single device operations
Error messages
Quick status checks
Configuration queries

Example: Test Results

Summary Response:

{
  "success": false,
  "data": {
    "tests_run": 45,
    "tests_passed": 43,
    "tests_failed": 2,
    "failed_tests": [
      "MyAppTests.LoginTests.testInvalidPassword",
      "MyAppTests.LoginTests.testEmptyCredentials"
    ],
    "cache_id": "test-run-def456"
  }
}

Full Details Query:

{
  "operation": "get-details",
  "cache_id": "test-run-def456",
  "detail_type": "full-log"
}

Token Efficiency:

Summary: ~200 tokens
Full log: ~3000 tokens
Savings: 93% for typical success cases

Caching Strategies

Cache-Friendly Operations

High Cache Value (Long TTL):

list operations (device list changes infrequently)
version operations (Xcode version is stable)
show-build-settings (project config changes rarely)

Moderate Cache Value (Medium TTL):

build operations (results valid until code changes)
test operations (results valid until code/tests change)
describe operations (UI state changes moderately)

Low Cache Value (Short TTL):

device-lifecycle (device state changes frequently)
app-lifecycle (app state is dynamic)
input/tap operations (UI interactions modify state)

Cache TTL Guidelines

// Recommended TTL values
{
  simulator_list: 1800,      // 30 minutes
  device_state: 60,          // 1 minute
  build_results: 3600,       // 1 hour
  test_results: 3600,        // 1 hour
  xcode_version: 86400,      // 24 hours
  project_schemes: 3600,     // 1 hour
  accessibility_tree: 10     // 10 seconds
}

Cache Invalidation Triggers

Automatic Invalidation:

TTL expiration
Memory pressure (LRU eviction)
Conflicting operation (e.g., clean invalidates build cache)

Manual Invalidation:

{
  "operation": "cache",
  "sub_operation": "clear",
  "parameters": {
    "cache_type": "simulator|project|response|all"
  }
}

Smart Invalidation:

File modification detection (build cache)
State change detection (device cache)
Operation sequence analysis (test cache)

Memory vs Disk Caching

In-Memory Cache (Default):

Pros: Fast access, no I/O overhead
Cons: Lost on process restart
Use For: Session-scoped data, frequently accessed data

Disk Cache (Optional):

Pros: Persists across restarts, larger capacity
Cons: I/O overhead, synchronization complexity
Use For: Build artifacts, test results, expensive queries

Enable Disk Persistence:

{
  "operation": "persistence",
  "sub_operation": "enable",
  "parameters": {
    "cache_dir": "/tmp/xc-cache"
  }
}

Configuration Management

Xcode Preferences

Query Build Settings:

{
  "operation": "show-build-settings",
  "scheme": "MyApp",
  "configuration": "Debug"
}

Common Settings to Cache:

PRODUCT_BUNDLE_IDENTIFIER
DEVELOPMENT_TEAM
CODE_SIGN_IDENTITY
SDKROOT
ARCHS

Use Case:

Validate configuration consistency
Debug build issues
Generate documentation
Audit security settings

Simulator Settings

Query Simulator Configuration:

{
  "operation": "list",
  "parameters": {
    "runtime": "iOS 17.0",
    "device_type": "iPhone"
  }
}

Persist Simulator State:

Boot order (preferred device)
Location simulation settings
Accessibility preferences
Network conditions

Build Configurations

Debug vs Release Configuration:

Debug:

{
  "configuration": "Debug",
  "options": {
    "parallel": true,
    "quiet": false
  }
}

Optimizations: Off
Symbols: Included
Token Impact: Verbose logs (~2000 tokens)
Cache Strategy: Short TTL (code changes frequently)

Release:

{
  "configuration": "Release",
  "options": {
    "parallel": true,
    "quiet": true
  }
}

Optimizations: On
Symbols: Optional
Token Impact: Quiet logs (~300 tokens)
Cache Strategy: Long TTL (less frequent)

Environment Variables

Set Test Environment:

{
  "operation": "app-lifecycle",
  "sub_operation": "launch",
  "device_id": "iPhone 15",
  "app_identifier": "com.example.MyApp",
  "parameters": {
    "environment": {
      "API_URL": "https://staging.example.com",
      "MOCK_DATA": "true",
      "LOG_LEVEL": "debug"
    }
  }
}

Common Environment Variables:

API_URL - Backend endpoint
FEATURE_FLAGS - Enable/disable features
TEST_MODE - Testing-specific behavior
LOG_LEVEL - Logging verbosity

Best Practices

1. Minimize Context Window Usage

Use Progressive Disclosure:

// Good: Request summary first
{
  "operation": "list",
  "parameters": { "concise": true }
}

// Then query details only if needed
{
  "operation": "get-details",
  "cache_id": "sim-list-xyz"
}

Avoid Verbose Operations:

// Bad: Always verbose
{
  "operation": "build",
  "options": { "verbose": true }
}

// Good: Quiet by default, verbose on errors
{
  "operation": "build",
  "options": { "quiet": true }
}

2. Cache Expensive Operations

Identify Expensive Operations:

build (20-120 seconds)
test (10-300 seconds)
list with large device sets (1-5 seconds)
describe with complex UI (0.5-2 seconds)

Cache Strategy:

// First call: Execute and cache
{
  "operation": "list"
}
// Response includes cache_id

// Subsequent calls: Use cached data
{
  "operation": "get-details",
  "cache_id": "previous-cache-id"
}

3. Clear State Between Test Runs

Clean State Pattern:

1. Cache clear (all)
2. Simulator erase
3. App uninstall
4. Fresh app install
5. Launch with test environment
6. Run tests
7. Cache clear (response)

Why Each Step:

Cache clear: No stale data influencing tests
Simulator erase: Clean device state
App uninstall: Remove app data/preferences
Fresh install: Simulate first-time user
Test environment: Consistent configuration
Response cache clear: Clean logs for next run

4. Handle Stale Cache Gracefully

Detect Stale Cache:

// Check cache timestamp
if (cache_age > ttl) {
  invalidateCache(cache_id);
  refetch();
}

Recovery Strategy:

// If cache miss or stale:
{
  "operation": "original-operation",
  // Original parameters
}
// Plugin automatically refreshes cache

User Pattern:

Try cached query first
If data seems stale, force refresh
Update cache with new results

5. Token Efficiency Metrics

Track Token Usage:

Summary responses: ~100-300 tokens
Full responses: ~1000-5000 tokens
Progressive disclosure savings: 80-95%

Optimization Checklist:

Use concise: true for list operations
Request summary output format for builds
Query cache_id before full details
Use quiet: true for non-debug builds
Enable response caching for repeated queries

6. Configuration File Examples

Build Configuration:

{
  "scheme": "MyApp",
  "configurations": {
    "debug": {
      "configuration": "Debug",
      "destination": "platform=iOS Simulator,name=iPhone 15",
      "cache_strategy": "short_ttl",
      "output_format": "summary"
    },
    "release": {
      "configuration": "Release",
      "destination": "generic/platform=iOS",
      "cache_strategy": "long_ttl",
      "output_format": "detailed"
    }
  }
}

Test Configuration:

{
  "test_scheme": "MyAppTests",
  "test_devices": [
    "iPhone 15",
    "iPad Pro (12.9-inch)"
  ],
  "clean_state": true,
  "cache_results": true,
  "parallel_execution": false,
  "environment": {
    "TEST_MODE": "true",
    "MOCK_NETWORK": "true"
  }
}

Cache Configuration:

{
  "cache": {
    "enabled": true,
    "ttl": {
      "simulator_list": 1800,
      "build_results": 3600,
      "test_results": 3600,
      "device_state": 60
    },
    "persistence": {
      "enabled": true,
      "path": "/tmp/xc-cache",
      "max_size_mb": 500
    },
    "invalidation": {
      "auto_invalidate_on_build": true,
      "auto_invalidate_on_test": false
    }
  }
}

Integration with MCP Tools

This Skill applies to all xc-plugin MCP tools:

Cache-Aware Tools:

xcodebuild-list - Returns cache_id for project data
xcodebuild-build - Returns cache_id for build logs
xcodebuild-test - Returns cache_id for test results
simctl-list - Returns cache_id for device lists
idb-ui-describe - Returns cache_id for UI trees

Cache Management Tools:

xcodebuild-get-details - Query cached build data
simctl-get-details - Query cached simulator data
cache - Manage cache configuration
persistence - Configure disk caching

Related Skills

simulator-workflows: Device management operations
xcode-workflows: Build system operations
ui-automation-workflows: Accessibility tree caching
ios-testing-patterns: Test state management

Related Resources

xc://reference/cache-architecture - Cache implementation details
xc://reference/token-optimization - Token efficiency guide
xc://workflows/progressive-disclosure - Pattern documentation
xc://reference/configuration - Configuration reference

Remember: Progressive disclosure first, full details only when needed. Cache expensive operations. Clear state between tests. 85-90% token savings are achievable with proper state management.