/state-management

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:

1. **Optimize Token Usage**

• Working with large device lists or build logs
• Reducing context window consumption
• Implementing efficient query patterns

2. **Manage Cache State**

• Understanding when responses are cached
• Invalidating stale cache entries
• Querying cached data efficiently

3. **Handle Configuration**

• Setting up consistent build environments
• Managing simulator preferences
• Configuring test execution parameters

4. **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: 1. **Summary** - Key metrics and booted devices (~100 tokens) 2. **cache_id** - Reference to full dataset 3. **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_