Mobileappfix

Autonomous Mobile App Debugging (/mobileappfix)

Recommended: Use /repair instead - it auto-detects web vs mobile and routes appropriately. /mobileappfix is the internal mobile debugging skill. Use it directly only when you specifically want mobile debugging without platform detection.

Autonomous debugging for React Native/Expo apps. Iterates until Maestro E2E tests pass.

Note: Both /mobileappfix and /appfix share the same autonomous-state.json with "mode": "repair". The /repair skill handles the routing automatically.

Triggers

• /mobileappfix
• "fix the mobile app"
• "Maestro tests failing"
• "app crashes on startup"

CRITICAL: Maestro MCP Required

YOU MUST USE MAESTRO MCP FOR ALL TESTING AND VALIDATION.

This skill requires a Maestro MCP server for test execution. The MCP provides:

• Full user journey orchestration
• Screenshot capture and analysis
• Element inspection and interaction
• Test result aggregation

DO NOT use bash maestro test commands. Always use Maestro MCP tools.

Pre-Flight: Verify Maestro MCP Available

Before any testing, verify Maestro MCP tools are available using ToolSearch(query: "maestro").

Actual MCP tool names (note the oli4 suffix from the forked Maestro):

mcp__maestro-oli4-mcp__list_devices          - List simulators/emulators
mcp__maestro-oli4-mcp__run_flow              - Execute inline Maestro commands
mcp__maestro-oli4-mcp__run_flow_files        - Execute Maestro flow YAML files
mcp__maestro-oli4-mcp__inspect_view_hierarchy - Get element tree
mcp__maestro-oli4-mcp__take_screenshot       - Capture screenshots
mcp__maestro-oli4-mcp__tap_on                - Tap elements
mcp__maestro-oli4-mcp__input_text            - Enter text

If Maestro MCP is not available, STOP and inform the user:

"Maestro MCP server is required. See setup guide: ~/.claude/skills/mobileappfix/references/maestro-mcp-setup.md"

If Android and getting UNAVAILABLE errors: The Maestro driver APKs need to be installed manually. See maestro-mcp-setup.md for the required commands.

CRITICAL: Autonomous Execution

THIS WORKFLOW IS 100% AUTONOMOUS. YOU MUST:

1. NEVER ask for confirmation - No "Should I rebuild?", "Should I commit?"
2. Auto-commit and push - When fixes are applied, commit immediately
3. Auto-rebuild - Trigger builds without asking
4. Complete verification - Run Maestro tests via MCP on simulator
5. Fill out checkpoint honestly - The stop hook checks your booleans

Only stop when the checkpoint can pass.

Workflow

┌─────────────────────────────────────────────────────────────────────┐
│  PHASE 0: PRE-FLIGHT                                                │
│     └─► ToolSearch(query: "maestro") to find MCP tools              │
│     └─► mcp__maestro-oli4-mcp__list_devices() to verify connection  │
│     └─► If Android + UNAVAILABLE: Run setup script (see setup.md)   │
│     └─► Read mobile-topology.md for project config                  │
├─────────────────────────────────────────────────────────────────────┤
│  PHASE 1: PLAN (First Iteration Only)                               │
│     └─► EnterPlanMode                                               │
│     └─► Explore: app structure, .maestro/ tests, recent commits     │
│     └─► ExitPlanMode                                                │
├─────────────────────────────────────────────────────────────────────┤
│  PHASE 2: FIX-VERIFY LOOP (via Maestro MCP)                         │
│     └─► Run FULL user journeys via MCP (not single tests)           │
│     └─► Minimum: J2 + J3 journeys (login + navigation)              │
│     └─► If pass: Update checkpoint, stop                            │
│     └─► If fail: Diagnose via MCP hierarchy, fix code, re-run       │
├─────────────────────────────────────────────────────────────────────┤
│  PHASE 3: COMPLETE                                                  │
│     └─► Commit: git commit -m "mobileappfix: [description]"         │
│     └─► Create checkpoint with honest booleans                      │
│     └─► Stop (hook validates checkpoint)                            │
└─────────────────────────────────────────────────────────────────────┘

Required: Full User Journey Validation

Single test files are NOT sufficient. You MUST validate complete user journeys.

Minimum Journey Set (MANDATORY)

Full Journey Set (Recommended)

Running Journeys via MCP

# Use Maestro MCP tools, NOT bash commands:
mcp__maestro-oli4-mcp__run_flow_files(
  device_id: "emulator-5554",  # or iOS simulator ID
  flow_files: "/absolute/path/to/.maestro/journeys/J2-returning-user-login.yaml"
)

mcp__maestro-oli4-mcp__run_flow_files(
  device_id: "emulator-5554",
  flow_files: "/absolute/path/to/.maestro/journeys/J3-main-app-navigation.yaml"
)

# IMPORTANT: Use absolute paths for flow_files

# DO NOT USE:
# maestro test .maestro/journeys/J2-*.yaml  ❌ (bash command)

MCP vs Bash Commands

ALWAYS prefer MCP tools over bash commands:

Simulator Commands (Bash OK)

# These bash commands are acceptable (not Maestro):
xcrun simctl boot "iPhone 15 Pro"
open -a Simulator
npm start --reset-cache
npm run ios
npm run prebuild:clean && cd ios && pod install && cd ..

Completion Checkpoint

Before stopping, create .claude/completion-checkpoint.json:

{
  "self_report": {
    "is_job_complete": true,
    "code_changes_made": true,
    "linters_pass": true,
    "category": "bugfix"
  },
  "reflection": {
    "what_was_done": "Fixed auth guard timing, login flow works",
    "what_remains": "none",
    "key_insight": "Reusable lesson for future sessions (>50 chars)",
    "search_terms": ["auth", "maestro", "mobile"]
  },
  "evidence": {
    "mcp_tools_used": [
      "mcp__maestro-oli4-mcp__run_flow_files",
      "mcp__maestro-oli4-mcp__take_screenshot",
      "mcp__maestro-oli4-mcp__inspect_view_hierarchy"
    ],
    "maestro_flows_tested": [
      "J2-returning-user-login.yaml",
      "J3-main-app-navigation.yaml"
    ],
    "platform": "ios",
    "device": "iPhone 15 Pro Simulator"
  }
}

Extra fields (evidence, mcp_tools_used, etc.) are allowed — the stop-validator ignores unknown keys. If validation fails, the blocking message shows exact requirements.

Maestro MCP Artifacts

The Maestro MCP automatically saves test evidence to .claude/maestro-smoke/.

MCP tools handle artifact creation - no manual bash commands needed:

# Use the run_flow tool discovered via ToolSearch(query: "maestro")
run_flow(flow: "...", output_dir: ".claude/maestro-smoke/")

Environment Variables

Exit Conditions

Skill Fluidity

You may use techniques from any skill for sub-problems without switching modes. Your autonomous state and checkpoint remain governed by /mobileappfix.

Reference Files