debug-code-profiling

Skill: Debug Code with Profiling

When to Use This Skill

This skill activates when you need to:

• Debug performance issues in code
• Find bottlenecks and slow execution paths
• Optimize code based on measured data (not guesswork)
• Identify the critical path before making suggestions
• Time execution to understand where time is spent

Critical Rule: Profile First, Suggest Second

Never make optimization or debugging suggestions without first:

1. Running detailed profiling to collect real data
2. Identifying and timing the critical path
3. Documenting measured baseline metrics

Prerequisites

Before using this skill, ensure:

• You have access to the relevant codebase and can run it in an appropriate environment
• You have permission to run profiling and performance tools on the target environment (local, CI, or production-like)
• The necessary profiling tools are installed for the target language/runtime (for example, Python cProfile, Node.js --prof/profilers, browser devtools, or APM/profiling agents)
• You can execute a representative workload, test suite, or scenario that reproduces the performance issue

Step-by-Step Workflow

Step 1: Run Profiling (REQUIRED – Do Not Skip)

Collect profiling data before any suggestions.

Python

cProfile (Built-in):

# Profile entire script
python -m cProfile -o profile_output.prof your_script.py

# Profile with sort by cumulative time
python -m cProfile -s cumtime your_script.py

# Profile specific function
python -c "
import cProfile
import pstats
import your_module
profiler = cProfile.Profile()
profiler.enable()
your_module.function_to_profile()
profiler.disable()
stats = pstats.Stats(profiler)
stats.sort_stats('cumulative')
stats.print_stats(20)
"

line_profiler (Line-by-line):

pip install line_profiler
kernprof -l -v your_script.py

py-spy (Sampling, no code changes):

pip install py-spy
py-spy top -- python your_script.py
py-spy record -o profile.svg -- python your_script.py