Memory Debugging

Systematic memory leak diagnosis using Instruments. This skill covers the 5 leak patterns responsible for 90% of real-world iOS memory issues.

When to Use This Skill

Use this skill when you're:

• Seeing app memory grow progressively during use (50MB → 100MB → 200MB)
• Finding multiple instances of the same view controller in Instruments
• Getting crashes after 10-15 minutes with no error message
• Instruments shows retain cycles or leaked objects
• View controllers don't deallocate after dismiss

Time investment: 15-30 minutes with this skill vs 2-3 hours hunting without it.

Example Prompts

Questions you can ask Claude that will draw from this skill:

• "My app crashes after 10-15 minutes of use with no error messages. How do I find the leak?"
• "Memory jumps from 50MB to 200MB+ on a specific action. Is this a leak or normal caching?"
• "View controllers don't deallocate after dismiss. How do I find the retain cycle?"
• "I have timers and observers that might be leaking. How do I verify and fix?"
• "My app uses 200MB. Is that normal or do I have multiple leaks?"
• "How do I set up Instruments to track memory leaks?"
• "How do I verify my fix actually worked?"

What This Skill Provides

The 5 Leak Patterns (90% of Real Issues)

1. Closure Capture Leaks – self captured strongly in escaping closures
2. Delegate Cycles – Strong delegate references creating mutual retention
3. Timer Leaks – Repeating timers holding strong references
4. NotificationCenter Leaks – Observers not removed in deinit
5. Parent-Child Cycles – Navigation or container relationships

Instruments Workflows

• Allocations instrument setup and heap snapshots
• Reference count tracking and retain cycle visualization
• Mark Generation technique for isolating leaks
• Memory Graph Debugger for finding retainers

Diagnostic Decision Tree

• Progressive growth vs temporary spikes
• Leak vs expected cache behavior
• Normal memory use vs problematic patterns

Verification Patterns

• deinit logging to confirm deallocation
• Heap snapshot comparison before/after
• Regression testing for leaks

MetricKit Memory Exception Diagnostics (iOS 27)

• DiagnosticReport with .memoryException delivers the call stack at a memory-limit kill (iOS 27)
• .backgroundTermination/.foregroundTermination metrics break out memoryLimitTerminationCount

Key Pattern

Closure Capture Fix

// ❌ LEAKS: Strong capture of self
viewModel.onUpdate = {
    self.updateUI()  // self captured strongly
}

// ✅ SAFE: Weak capture
viewModel.onUpdate = { [weak self] in
    self?.updateUI()
}

// ✅ Verify fix worked
deinit {
    print("ViewController deallocated")  // Should print on dismiss
}

Quick Diagnosis Checklist

1. Does the class have deinit? Add one with a print statement
2. Does deinit fire when expected? If not, leak exists
3. Check: closures, delegates, timers, observers
4. Use Memory Graph Debugger to find the retainer

Documentation Scope

This page documents the axiom-performance skill — systematic leak diagnosis workflows Claude uses when helping you debug memory issues. The skill contains complete Instruments setup, pattern recognition, heap analysis techniques, and production crisis handling.

For quick scanning: Use /axiom:audit-memory to scan your codebase for the 6 most common leak patterns automatically.

Related

• /axiom:audit-memory – Quick automated scan for leak patterns in code
• memory-auditor – Autonomous agent for codebase-wide leak detection
• performance-profiling – Broader profiling including CPU and energy
• swift-concurrency – Actor patterns that prevent some leak types
• metrickit-ref – DiagnosticReport.memoryException and MetricManager setup for iOS 27 memory-kill diagnostics

Resources

WWDC: 2021-10180, 2022-10106, 2024-10173, 2026-222

Docs: /instruments, /xcode/debugging-and-testing, /metrickit/metricmanager