Debugging Instruments
Diagnose iOS crashes, leaks, hangs, and performance regressions with LLDB, Memory Graph, and Instruments before release.
Overview
Debugging-instruments is an agent skill most often used in Ship (also Operate errors, Build backend) that walks through LLDB, Memory Graph, hang detection, and Instruments profiling for iOS apps.
Install
npx skills add https://github.com/dpearson2699/swift-ios-skills --skill debugging-instrumentsWhat is this skill?
- LLDB essentials: po, p, v, backtraces, frame selection, and thread listing for crash triage
- Memory Graph Debugger workflow for leaks, retain cycles, and unexpected strong references
- Hang diagnostics for main-thread blocking and UI unresponsiveness
- Build failure triage steps when Xcode errors obscure the root cause
- Instruments overview for CPU, memory, energy, and network profiling
- Coverage spans LLDB, Memory Graph, hang diagnostics, build failure triage, and Instruments (CPU, memory, energy, network
- Includes a dedicated review checklist before closing a debug session
Adoption & trust: 1.8k installs on skills.sh; 713 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your iOS build crashes, leaks memory, hangs on the main thread, or feels slow and you are guessing instead of using a repeatable Apple tooling workflow.
Who is it for?
Indie iOS builders shipping on Xcode who debug locally with LLDB and Instruments and want agent-guided command and workflow order.
Skip if: Server-side-only teams, non-Apple platforms, or projects where debugging is fully outsourced to a crash reporting SaaS with no local repro.
When should I use this skill?
Diagnosing iOS crashes, memory leaks, retain cycles, main thread hangs, slow rendering, build failures, or profiling CPU, memory, energy, and network usage.
What do I get? / Deliverables
You end with a traced root cause, memory or hang hypothesis validated in Instruments, and checklist-reviewed fix direction before shipping or patching.
- Documented repro steps and LLDB or Instruments findings
- Checklist-reviewed diagnosis with likely fix category (memory, threading, network, build config)
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Pre-release verification and defect isolation belong on the Ship → testing shelf even when the same workflows continue in production operations. Testing subphase covers manual and tooling-driven validation—breakpoints, memory graphs, and Instruments runs—before you call a build shippable.
Where it fits
Reproduce a TestFlight crash and walk the LLDB backtrace before tagging a release.
Investigate a spike in hangs reported in the field using Instruments time profiler templates.
Profile scroll performance and memory during a heavy SwiftUI list implementation.
How it compares
On-device Apple debugging playbook, not a remote crash analytics integration or automated XCTest generator.
Common Questions / FAQ
Who is debugging-instruments for?
Solo iOS developers and small teams using Xcode who need structured LLDB, Memory Graph, and Instruments steps when quality or production issues appear.
When should I use debugging-instruments?
Use it in Ship while testing release candidates, in Operate when investigating crashes or hangs in the field, and during Build when profiling CPU, memory, energy, or network during feature work.
Is debugging-instruments safe to install?
The skill is diagnostic documentation; review the Security Audits panel on this Prism page for the hosting repository before install.
SKILL.md
READMESKILL.md - Debugging Instruments
# Debugging and Instruments Diagnose crashes, memory leaks, retain cycles, main thread hangs, and performance bottlenecks in iOS apps using LLDB, Memory Graph Debugger, and Instruments. Covers breakpoint workflows, memory graph analysis, hang detection, build failure triage, and Instruments profiling for CPU, memory, energy, and network. ## Contents - [LLDB Debugging](#lldb-debugging) - [Memory Debugging](#memory-debugging) - [Hang Diagnostics](#hang-diagnostics) - [Build Failure Triage](#build-failure-triage) - [Instruments Overview](#instruments-overview) - [Common Mistakes](#common-mistakes) - [Review Checklist](#review-checklist) - [References](#references) ## LLDB Debugging ### Essential Commands ```text (lldb) po myObject # Print object description (calls debugDescription) (lldb) p myInt # Print with type info (uses LLDB formatter) (lldb) v myLocal # Frame variable — fast, no code execution (lldb) bt # Backtrace current thread (lldb) bt all # Backtrace all threads (lldb) frame select 3 # Jump to frame #3 in the backtrace (lldb) thread list # List all threads and their states (lldb) thread select 4 # Switch to thread #4 ``` Use `v` over `po` when you only need a local variable value — it does not execute code and cannot trigger side effects. ### Breakpoint Management ```text (lldb) br set -f ViewModel.swift -l 42 # Break at file:line (lldb) br set -n viewDidLoad # Break on function name (lldb) br set -S setValue:forKey: # Break on ObjC selector (lldb) br modify 1 -c "count > 10" # Add condition to breakpoint 1 (lldb) br modify 1 --auto-continue true # Log and continue (logpoint) (lldb) br command add 1 # Attach commands to breakpoint > po self.title > continue > DONE (lldb) br disable 1 # Disable without deleting (lldb) br delete 1 # Remove breakpoint ``` ### Expression Evaluation ```text (lldb) expr myArray.count # Evaluate Swift expression (lldb) e -l swift -- import UIKit # Import framework in LLDB (lldb) e -l swift -- self.view.backgroundColor = .red # Modify state at runtime (lldb) e -l objc -- (void)[CATransaction flush] # Force UI update after changes ``` After modifying a view property in the debugger, call `CATransaction.flush()` to see the change immediately without resuming execution. ### Watchpoints ```text (lldb) w set v self.score # Break when score changes (lldb) w set v self.score -w read # Break when score is read (lldb) w modify 1 -c "self.score > 100" # Conditional watchpoint (lldb) w list # Show active watchpoints (lldb) w delete 1 # Remove watchpoint ``` Watchpoints are hardware-backed (limited to ~4 on ARM). Use them to find unexpected mutations — the debugger stops at the exact line that changes the value. ### Symbolic Breakpoints Set breakpoints on methods without knowing the file. Useful for framework or system code: ```text (lldb) br set -n "UIViewController.viewDidLoad" (lldb) br set -r ".*networkError.*" # Regex on symbol name (lldb) br set -n malloc_error_break # Catch malloc corruption (lldb) br set -n UIViewAlertForUnsatisfiableConstraints # Auto Layout issues ``` In Xcode, use the Breakpoint Navigator (+) to add symbolic breakpoints for common diagnostics like `-[UIApplication main]` or `swift_willThrow`. ## Memory Debugging ###