Performance debugging

Performance Debugging

Use this skill when the main problem is not correctness, but speed, responsiveness, or resource usage.

Goal

Increase success rate for performance work by following this order:

1. confirm the slowdown is real
2. measure the slow path
3. locate the bottleneck
4. identify the class of performance problem
5. make the smallest meaningful optimization
6. re-measure to confirm improvement
7. keep correctness intact

Core Rules

1. Measure before optimizing

Do not start by guessing what is slow.

First capture:

• what feels slow
• where it appears slow
• how it is reproduced
• what input size or workflow triggers it
• what "fast enough" would mean

Prefer concrete evidence over intuition.

2. Separate the symptom from the bottleneck

Visible slowness is not always caused by the place it appears.

Distinguish between:

• symptom: where the user notices lag
• slow path: the operation that takes too long
• bottleneck: the actual limiting step
• cause: the underlying design, algorithm, I/O, or rendering choice creating the bottleneck

3. Classify the performance problem

Try to determine whether the issue is mainly:

• CPU/algorithmic work
• file I/O or network I/O
• repeated work that should be cached or avoided
• too much rendering or DOM/UI work
• too much state churn or event handling
• unnecessary startup or initialization cost
• oversized data loading or transformation

4. Optimize the narrowest hot path first

Prefer the smallest change that removes the biggest cost.

Avoid:

• broad rewrites before bottlenecks are proven
• replacing readable code with complexity for tiny gains
• premature caching everywhere
• optimizing code paths that are not actually hot

5. Re-measure after each meaningful change

After an optimization, compare:

• before vs after runtime
• before vs after responsiveness
• same input / same workflow
• any regression in correctness or clarity

If the improvement is negligible, reconsider the approach.

6. Keep correctness and maintainability visible

Performance fixes should not silently break behavior.

Before calling an optimization done, check:

• correctness still holds
• tests still pass where relevant
• the code is still understandable
• the tradeoff is worth the complexity added

Minis-Specific Workflow

Shell-first measurement

Use shell tools to:

• reproduce the slow command or script
• time targeted operations
• compare repeated runs
• isolate slow file/network/process steps
• create minimal benchmarks or repro scripts

Browser-visible performance

For web apps or HTML tools, look for:

• slow initial load
• lag after click/input
• heavy rerendering or visible stutter
• delayed text/state updates
• slow route transitions or form submission

Use browser testing to confirm the visible symptom, then pair it with code-level or shell-based evidence.

Small benchmark bias

Prefer compact, task-specific measurement over large vague profiling sessions.

Examples:

• one slow function call
• one repeated render path
• one route load
• one script invocation with representative input

Investigation Sequence

Use this order:

1. Restate the performance symptom.
2. Reproduce it reliably.
3. Measure the relevant path.
4. Identify the slowest step or hottest path.
5. Classify the problem type.
6. Propose the smallest meaningful optimization.
7. Re-measure after the change.
8. Check correctness and nearby regressions.
9. Summarize the tradeoff.

Common Performance Failure Modes

Watch for:

• repeated work inside loops
• unnecessary parsing or recomputation
• loading too much data at once
• UI handlers doing heavy logic synchronously
• expensive rendering triggered too often
• slow startup due to too much initialization
• using an inefficient algorithm for growing input sizes
• hidden I/O cost mistaken for CPU cost
• optimization attempts that move the bottleneck elsewhere

Heuristics

Prefer:

• representative inputs
• same-condition before/after measurements
• hot-path optimization over blanket optimization
• simpler improvements before deeper rewrites
• evidence-backed tradeoffs

Be cautious when:

• timing varies heavily run to run
• network or remote services distort local measurement
• browser-visible lag has multiple possible causes
• the workload is too small to measure meaningfully
• the optimization makes the code much harder to maintain

Integration with Other Skills

• Use root-cause-tracing if the slowdown may be a symptom of a deeper state or logic issue.
• Use test-driven-development if behavior must be locked down before performance changes.
• Use webapp-testing to confirm visible UI responsiveness before and after the fix.
• Use finishing-a-development-branch when the optimization is done and needs final validation and cleanup.
• Use software-architecture if the true cause is structural and the optimization requires redesign rather than tuning.

Completion Checklist

Before calling the performance task done, check:

• Was the slowdown reproduced clearly?
• Was the bottleneck actually measured?
• Was the optimization applied to the hot path?
• Was before/after improvement confirmed?
• Did correctness still hold?
• Was complexity kept reasonable?
• Is the tradeoff clearly explained?

Response Template

• Performance symptom:
• Reproduction:
• Measured path:
• Bottleneck:
• Problem type:
• Optimization made:
• Before/after evidence:
• Remaining tradeoff:
• Suggested next step:

Example Triggers

• "This works, but it's too slow — find the bottleneck first."
• "Help me optimize this without guessing."
• "Why is this page/script so sluggish?"
• "Measure before changing the code and tell me what's actually slow."
• "Improve the performance of this flow without breaking correctness."