/debug-menu

name: debug-menu
description: Generates a developer debug menu with feature flag toggles, environment switching, network log viewer, cache clearing, crash trigger, and diagnostic info export. Only included in DEBUG builds. Use when user wants a debug panel, dev tools menu, or shake-to-debug functionality.
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
last_verified: 2026-07-16
review_by: 2027-06-22
os_version: iOS 27 / macOS 27

Debug Menu Generator

Generate a comprehensive developer debug menu accessible via shake gesture or hidden tap. Includes feature flag toggles, environment switching, network log viewer, cache clearing, crash trigger, and diagnostic info export. All code is wrapped in `#if DEBUG` so it never ships to production.

When This Skill Activates

Use this skill when the user:

• Asks for a "debug menu" or "developer menu"
• Wants "dev tools" or a "debug panel"
• Mentions "shake to debug" or "diagnostic menu"
• Wants to "toggle feature flags" from the app
• Asks about "environment switching" (dev/staging/production)
• Wants a "network log viewer" in the app

Pre-Generation Checks

1. Project Context Detection

• [ ] Check deployment target (iOS 17+ / macOS 14+ required for @Observable)
• [ ] Check Swift version (requires Swift 5.9+)
• [ ] Identify source file locations and project structure

2. Conflict Detection

Search for existing debug/dev menu code:

Glob: **/*Debug*Menu*.swift, **/*DevMenu*.swift, **/*DevTools*.swift, **/*DebugPanel*.swift
Grep: "DebugMenu" or "DevMenu" or "motionEnded" or "shake" in *.swift

If existing debug menu found:

• Ask if user wants to replace or extend it
• If extending, integrate new sections into existing structure

3. Feature Flags Detection

Search for existing feature flag setup:

Glob: **/*FeatureFlag*.swift, **/*Feature*Toggle*.swift
Grep: "FeatureFlag" or "featureFlag" or "isFeatureEnabled"

If found, integrate debug menu toggles with existing feature flag system rather than creating a new one.

Configuration Questions

Ask user via AskUserQuestion:

1. **Access method?**

• Shake gesture (shake device to open)
• Hidden tap (5-tap on a hidden area)
• Both (shake + hidden tap) -- recommended

2. **Sections to include?** (multi-select)

• Feature flags (toggle flags on/off at runtime)
• Environment switcher (dev / staging / production)
• Network logs (recent requests with status codes and timing)
• Cache tools (clear image cache, HTTP cache, all caches)
• Crash trigger (force crash for Crashlytics testing)
• Diagnostics (device info, memory, disk, app version)

3. **Include push notification testing?**

• Yes (simulate local push notifications for testing)
• No

4. **Include export diagnostics?**

• Yes (share sheet with full diagnostic report)
• No

Generation Process

Step 1: Read Templates

Read `templates.md` for production Swift code wrapped in `#if DEBUG`.

Step 2: Create Core Files

Generate these files (all wrapped in `#if DEBUG`): 1. `DebugMenuView.swift` -- Main NavigationStack with all sections 2. `DebugSection.swift` -- Enum defining available debug sections

Step 3: Create Section Files

Based on configuration: 3. `DebugEnvironmentSwitcher.swift` -- If environment switcher selected 4. `DebugNetworkLogger.swift` -- If network logs selected 5. `DiagnosticInfo.swift` -- If diagnostics or export selected

Step 4: Create Trigger Files

6. `DebugMenuTrigger.swift` -- ShakeDetector + hidden tap gesture + ViewModifier

Step 5: Create Action Files

7. `DebugActions.swift` -- Collection of debug utility actions

Step 6: Determine File Location

Check project structure:

• If `Sources/` exists -> `Sources/DebugMenu/`
• If `App/` exists -> `App/DebugMenu/`
• Otherwise -> `DebugMenu/`

Entire folder is `#if DEBUG` and should be excluded from release builds.

Output Format

After generation, provide:

Files Created

DebugMenu/
├── DebugMenuView.swift            # Main NavigationStack with all sections
├── DebugSection.swift             # Enum of available sections
├── DebugEnvironmentSwitcher.swift # Environment switching (optional)
├── DebugNetworkLogger.swift       # Network request logger (optional)
├── DiagnosticInfo.swift           # Device and app diagnostics (optional)
├── DebugMenuTrigger.swift         # Shake gesture + hidden tap trigger
└── DebugActions.swift             # Utility actions (reset, clear, crash)

Integration Steps

**Add the debug trigger to your root view:**

#if DEBUG
import SwiftUI

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .debugMenuTrigger()  // Adds shake + tap to open debug menu
        }
    }
}
#endif

**Or add only to specific views:**

struct SettingsView: View {
    var body: some View {
        Form {
            // ... your settings
        }
        #if DEBUG
        .debugMenuTrigger(method: .hiddenTap)
        #endif
    }
}

**Hook up the network logger to your API client:**

#if DEBUG
func performRequest(_ request: URLRequest) async throws -> (Data, URLResponse) {
    let start = Date()
    let (data, response) = try await session.data(for: request)
    DebugNetworkLogger.shared.log(request: request, response: response, data: data, duration: Date().timeIntervalSince(start))
    return (data, response)
}
#endif

**Register your feature flags:**

#if DEBUG
extension DebugMenuView {
    static let featureFlags: [FeatureFlag] = [
        FeatureFlag(key: "new_onboarding", title: "New Onboarding Flow", defaultValue: false),
        FeatureFlag(key: "dark_mode_v2", title: "Dark Mode V2", defaultValue: false),
        FeatureFlag(key: "premium_paywall", title: "Premium Paywall", defaultValue: true),
    ]
}
#endif

Testing

#if DEBUG
@Test
func debugMenuSectionsRender() {
    let view = DebugMenuView()
    // Verify all sections a