Systematic diagnosis and resolution of app hangs. A hang occurs when the main thread is blocked for more than 1 second, making the app unresponsive to user input.
Fetches axiom-hang-diagnostics from charleswiltgen/axiom and configures it for Cursor.
3
Select Cursor when prompted
The CLI shows a list of agents. Use arrow keys and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ────────────────
│ · Cline · Codex · Goose · Windsurf
│ ●Cursor(selected)
│ · Cursor · Aider · Continue
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/axiom-hang-diagnostics
Restart Cursor to activate axiom-hang-diagnostics. Access via /axiom-hang-diagnostics in your agent's command palette.
⚠
Security Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your environment. Always review source, verify the publisher, and test in isolation before production.
Systematic diagnosis and resolution of app hangs. A hang occurs when the main thread is blocked for more than 1 second, making the app unresponsive to user input.
Red Flags — Check This Skill When
Symptom
This Skill Applies
App freezes briefly during use
Yes — likely hang
UI doesn't respond to touches
Yes — main thread blocked
"App not responding" system dialog
Yes — severe hang
Xcode Organizer shows hang diagnostics
Yes — field hang reports
MetricKit MXHangDiagnostic received
Yes — aggregated hang data
Animations stutter or skip
Maybe — could be hitch, not hang
App feels slow but responsive
No — performance issue, not hang
What Is a Hang
A hang is when the main runloop cannot process events for more than 1 second. The user taps, but nothing happens.
User taps → Main thread busy/blocked → Event queued → 1+ second delay → HANG
Key distinction: The main thread handles ALL user input. If it's busy or blocked, the entire UI freezes.
Hang vs Hitch vs Lag
Issue
Duration
User Experience
Tool
Hang
>1 second
App frozen, unresponsive
Time Profiler, System Trace
Hitch
1-3 frames (16-50ms)
Animation stutters
Animation Hitches instrument
Lag
100-500ms
Feels slow but responsive
Time Profiler
This skill covers hangs. For hitches, see axiom-swiftui-performance. For general lag, see axiom-performance-profiling.
The Two Causes of Hangs
Every hang has one of two root causes:
1. Main Thread Busy
The main thread is doing work instead of processing events.
Subcategories:
Type
Example
Fix
Proactive work
Pre-computing data user hasn't requested
Lazy initialization, compute on demand
Irrelevant work
Processing all notifications, not just relevant ones
Filter notifications, targeted observers
Suboptimal API
Using blocking API when async exists
Switch to async API
2. Main Thread Blocked
The main thread is waiting for something else.
Subcategories:
Type
Example
Fix
Synchronous IPC
Calling system service synchronously
Use async API variant
File I/O
Data(contentsOf:) on main thread
Move to background queue
Network
Synchronous URL request
Use URLSession async
Lock contention
Waiting for lock held by background thread
Reduce critical section, use actors
Semaphore/dispatch_sync
Blocking on background work
Restructure to async completion
Decision Tree — Diagnosing Hangs
START: App hangs reported
│
├─→ Do you have hang diagnostics from Organizer or MetricKit?
│ │
│ ├─→ YES: Examine stack trace
│ │ │
│ │ ├─→ Stack shows your code running
│ │ │ → BUSY: Main thread doing work
│ │ │ → Profile with Time Profiler
│ │ │
│ │ └─→ Stack shows waiting (semaphore, lock, dispatch_sync)
│ │ → BLOCKED: Main thread waiting
│ │ → Profile with System Trace
│ │
│ └─→ NO: Can you reproduce?
│ │
│ ├─→ YES: Profile with Time Profiler first
│ │ │
│ │ ├─→ High CPU on main thread
│ │ │ → BUSY: Optimize the work
│ │ │
│ │ └─→ Low CPU, thread blocked
│ │ → Use System Trace to find what's blocking
│ │
│ └─→ NO: Enable MetricKit in app
│ → Wait for field reports
│ → Check Organizer > Hangs
Tool Selection
Scenario
Primary Tool
Why
Reproduces locally
Time Profiler
See exactly what main thread is doing
Blocked thread suspected
System Trace
Shows thread state, lock contention
Field reports only
Xcode Organizer
Aggregated hang diagnostics
Want in-app data
MetricKit
MXHangDiagnostic with call stacks
Need precise timing
System Trace
Nanosecond-level thread analysis
Time Profiler Workflow for Hangs
Launch Instruments → Select Time Profiler template
Record during hang → Reproduce the freeze
Stop recording → Find the hang period in timeline
Select hang region → Drag to select frozen timespan
Examine call tree → Look for main thread work
What to look for:
Functions with high "Self Time" on main thread
Unexpectedly deep call stacks
System calls that shouldn't be on main thread
System Trace Workflow for Blocked Hangs
Launch Instruments → Select System Trace template
Record during hang → Capture thread states
Find main thread → Filter to main thread
Look for red/orange → Blocked states
Examine blocking reason → Lock, semaphore, IPC
Thread states:
Running (blue): Executing code
Preempted (orange): Runnable but not scheduled
Blocked (red): Waiting for resource
Common Hang Patterns and Fixes
Pattern 1: Synchronous File I/O
Before (hangs):
// Main thread blocks on file readfuncloadUserData(){let data =try!Data(contentsOf: largeFileURL)// BLOCKSprocessData(data)}
After (async):
funcloadUserData(){Task.detached {let data =tryData(contentsOf: largeFileURL)awaitMainActor.run {self.processData(data)}}}
Pattern 2: Unfiltered Notification Observer
Before (processes all):
NotificationCenter.default.addObserver(self, selector:#selector(handleChange), name:.NSManagedObjectContextObjectsDidChange, object:nil// Receives ALL contexts)
After (filtered):
NotificationCenter.default.addObserver(self, selector:#selector(handleChange), name:.NSManagedObjectContextObjectsDidChange, object: relevantContext // Only this context)
// From background threadDispatchQueue.main.sync {// BLOCKS if main is blockedupdateUI()}
After (async):
DispatchQueue.main.async{self.updateUI()}
Pattern 5: Semaphore for Async Result
Before (blocks main thread):
funcfetchDataSync()->Data{let semaphore =DispatchSemaphore(value:0)var result:Data?URLSession.shared.dataTask(with: url){ data,_,_in result = data
semaphore.signal()}.resume() semaphore.wait()// BLOCKS MAIN THREADreturn result!}
After (async/await):
funcfetchData()asyncthrows->Data{let(data,_)=tryawaitURLSession.shared.data(from: url)return data
}
›Access to product documentation and roadmap tools (Jira, Notion, etc.)
›Understanding of product management frameworks (RICE, Jobs-to-be-Done, etc.)
›Stakeholder contact information and communication channels
Time Estimate
30-60 minutes to see productivity improvements
Steps
1Install product management skill
2Start with user story generation for known feature
3Progress to competitive analysis: research 2-3 competitors
4Use for roadmap prioritization: apply RICE/ICE scoring
5Draft stakeholder communications and refine based on feedback
6Build template library for recurring PM tasks
7Share effective prompts with product team
Common Pitfalls
⚠Not validating competitive research—verify facts before sharing
⚠Accepting user stories without involving engineering team
⚠Over-relying on frameworks without qualitative judgment
⚠Not customizing outputs to company culture and communication style
⚠Skipping stakeholder validation of generated requirements
Best Practices
✓ Do
+Validate research and competitive analysis with real data
+Collaborate with engineering when generating technical requirements
+Customize frameworks and templates to your company context
+Use skill for first drafts, refine with stakeholder input
+Document successful prompt patterns for PM tasks
+Combine AI efficiency with human judgment and intuition
✗ Don't
−Don't publish competitive analysis without fact-checking
−Don't finalize user stories without engineering review
−Don't make prioritization decisions solely on AI scoring
−Don't skip customer validation of generated requirements
−Don't ignore company-specific context and culture
💡 Pro Tips
★Provide context: company goals, constraints, customer feedback
★Ask for alternatives: 'Show 3 ways to prioritize this roadmap'
★Request stakeholder-specific formatting: 'Executive summary vs. engineering spec'
★Use skill for 70% generation + 30% customization to company needs
When to Use This
✓ Use when
Use for user story writing, competitive research, roadmap prioritization, stakeholder communication, and PRD drafting. Best for reducing repetitive documentation and research work.
✗ Avoid when
Avoid for strategic product vision (requires deep customer empathy), pricing decisions (needs market and financial expertise), or when face-to-face customer discovery is more valuable than speed.
Learning Path
1Basic: user stories, feature specs, status updates
