Debugging Difficult Bugs
Use early when debugging a medium or hard bug, especially when tests alone may not...
Install
npx skills add mastra-ai/mastra --skill debugging-difficult-bugs -g -a claude-code -y- Repository
- mastra-ai/mastra29.3k
- Category
- Design
- Updated
- 3d ago
- License
- See repository
- Context cost
- Mediumabout 1,729 tokens
- Runs scripts
- No, instructions only
What it does
Use early when debugging a medium or hard bug, especially when tests alone may not reveal the real runtime failure. Trigger this before extended TDD iteration when a bug involves runtime state, ordering, persistence, streaming, concurrency, UI/manual reproduction, external services, or when a red or newly passing test may not model the real issue. Skip only when the root cause is already directly proven by a stack trace or deterministic test that exercises the real runtime path.
Debugging Difficult Bugs
Use this skill early for medium or hard bugs where normal TDD may give false confidence because the test does not fully capture the real bug.
Core idea: instrument the actual runtime path, reproduce the real issue, then inspect append-only JSONL logs before deciding on a fix.
When to Use
Use this workflow near the start of debugging when any of these are true:
- The bug is medium or hard complexity, especially if it spans multiple functions, packages, processes, or UI/runtime boundaries.
- A test is red, but the failing test might be an incomplete model of the real bug.
- You are tempted to make a second speculative fix without new runtime evidence.
- The bug depends on runtime ordering, state, caching, streaming, concurrency, persistence, UI interaction, or external services.
- The user says they can reproduce the issue manually.
- The test passes after a change, but you are not confident it proves the actual reported bug is fixed.
Do not keep iterating only on tests if you do not understand the runtime behavior.
Skip this workflow only when the root cause is already directly proven by a stack trace or by a deterministic failing test that exercises the real runtime path. If you are tempted to make a second speculative fix, use this workflow.
Required Approach
- State the uncertainty
- Acknowledge that the current test may not capture the actual bug.
- Identify the real code path that must be observed.
