debugging-difficult-bugs

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.

Quality

75%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/debugging-difficult-bugs/SKILL.md

Quality

Content

77%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is highly actionable with executable code and a well-sequenced, checkpointed workflow including cleanup and verification. Its main weakness is conciseness and progressive disclosure: trigger conditions are duplicated from the frontmatter and all detail is inline rather than split into reference files.

Suggestions

Remove the 'When to Use' trigger list or trim it heavily, since the same conditions are already in the description frontmatter.

Move the per-language JSONL logging patterns and the reproduction-handoff template into a references/ file linked from the body to shorten the main SKILL.md.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient and free of concepts Claude already knows, but the 'When to Use' list repeats trigger conditions already in the frontmatter, and the full reproduction-handoff boilerplate plus the lengthy Node logging example could be tightened without losing clarity.	2 / 3
Actionability	Provides fully executable, copy-paste-ready code (the debugBug appendFileSync helper and call sites), a literal reproduction-handoff message, and concrete redaction examples — concrete and specific throughout.	3 / 3
Workflow Clarity	The six-step Required Approach is clearly sequenced with explicit checkpoints (analyze log before fixing, cleanup, final verification), plus an Analysis Checklist and Final Verification list that form a feedback loop for error recovery.	3 / 3
Progressive Disclosure	No bundle files exist and the content is well-organized into clear sections, but at ~175 lines everything is inline with no progressive split; the per-language logging patterns and reproduction templates are candidates to move into references.	2 / 3
	Total	10 / 12 Passed

Description

72%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description has excellent trigger-term coverage and a clear, distinctive niche, but it over-indexes on when-to-use conditions while leaving the skill's actual procedure implicit. Stating the concrete actions (instrument runtime, reproduce, inspect JSONL logs) would lift specificity and completeness.

Suggestions

Add an explicit 'what' clause naming the skill's concrete actions, e.g. 'Instruments the real runtime path with JSONL logs, reproduces the issue, then inspects the log before fixing.'

Lead with the procedure before the long trigger-condition list so the capability is clear in the first sentence.

Dimension	Reasoning	Score
Specificity	Names the debugging domain and some actions ('Use early during debugging', 'Trigger this before extended TDD iteration', 'Skip only when the root cause is already directly proven') but never states the skill's concrete operations — instrumenting the runtime path, reproducing the issue, inspecting JSONL logs — so it is not comprehensive on actions.	2 / 3
Completeness	The 'when' is explicit and thorough, but the 'what' is only implied as 'debugging' rather than stating the skill's actual procedure (instrument, reproduce, inspect logs), so it does not clearly answer both what and when.	2 / 3
Trigger Term Quality	Strong coverage of natural developer terms ('debugging a medium or hard bug', 'tests alone may not reveal the real runtime failure', 'runtime state, ordering, persistence, streaming, concurrency', 'red or newly passing test', 'stack trace', 'deterministic test') that a user would actually say when needing this skill.	3 / 3
Distinctiveness Conflict Risk	The trigger conditions (runtime state, ordering, persistence, streaming, concurrency, external services, false-confidence tests) carve out a distinct niche unlikely to fire for unrelated skills.	3 / 3
	Total	10 / 12 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: mastra-ai/mastra
Path: .claude/skills/debugging-difficult-bugs/SKILL.md
Commit: 3b78ed9

Reviewed: 1 day ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.