debug-performance

Debug Performance

Find and fix performance bottlenecks by measuring, not guessing.

Workflow

Measure → Identify → Analyze → Optimize → Confirm

1. Measure

Establish a baseline before touching anything:

tl parallel \
  "baseline=tl run '<benchmark or timed command>'" \
  "complexity=tl complexity <file>" \
  "hotspots=tl hotspots"

2. Identify

Find the actual bottleneck:

tl parallel \
  "flow=tl flow <function> <file>" \
  "deps=tl deps <file>" \
  "symbols=tl symbols <file>"

3. Analyze

Understand why it's slow:

tl parallel \
  "snippet=tl snippet <function> <file>" \
  "related=tl related <file>" \
  "scope=tl scope <function> <file>"

4. Optimize

Apply the fix based on the bottleneck type:

# Algorithmic change
tl flow <function> <file>     # Verify new path is simpler

# Caching opportunity
tl impact <file>              # How many callers benefit?

# Reducing I/O
tl deps <file>                # Identify unnecessary imports

# Parallelization
tl flow <function> <file>     # Confirm no shared state

5. Confirm

tl run "<same benchmark>"     # Measure improvement — no numbers, no claim

Decision tree

"It's slow" → Do you have a measurement?
  ├─ Yes (specific operation) → tl flow on that operation
  │   → tl snippet on each function in chain
  │   → Find the O(n^2) or blocking I/O
  ├─ Vague ("app is slow") → tl hotspots + tl complexity
  │   → Profile top 3 complex files
  │   → tl flow on entry points to find hot paths
  └─ Memory issue → tl deps on entry point
      → Look for large imports, circular refs
      → tl guard for circular deps

Tips

• Always benchmark before AND after — optimizations without numbers are guesses
• tl complexity > 10 on a function is a red flag for performance problems
• Check tl deps for heavy imports that could be lazy-loaded
• Don't optimize cold paths — use tl flow to confirm the function is on the hot path
• Use tl parallel for all context-gathering steps — they're independent