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

93%

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

Quality

Content

92%Weight 40%Scale 1-5

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

A well-structured, highly actionable debugging skill with a clear sequenced workflow, validation checkpoints, and copy-paste instrumentation code. It is concise with only minor redundancy against the description and is appropriately self-contained with no bundle files needed.

Dimension	Reasoning	Score
Conciseness	Mostly lean and assumes Claude's competence (e.g. compact JSONL code and a tight logging checklist), with only minor over-explanation such as restating the core idea and the 'When to Use' rationale that slightly overlaps the description.	4 / 5
Actionability	Provides copy-paste ready Node/TypeScript instrumentation code, concrete call-site examples at branches, a verbatim user-handoff message template, and a specific analysis checklist — fully executable guidance for the common cases.	5 / 5
Workflow Clarity	A clearly sequenced six-step workflow ('State the uncertainty' through 'Keep or improve tests') with explicit verification checkpoints (analyze log before fixing, regression test fails-before/passes-after, final-diff cleanup checklist).	5 / 5
Progressive Disclosure	No bundle files exist, so all content lives in SKILL.md; it is well-organized into clearly headed sections (When to Use, Required Approach, JSONL Logging Pattern, What to Log, Reproduction Handoff, Analysis Checklist, Final Verification) with no nested references, which suits a self-contained skill.	5 / 5
	Total	19 / 20 Passed

Description

95%Weight 40%Scale 1-5

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

A strong, specific description that clearly states both what the skill does and when to use it, with rich natural trigger terms and a distinctive niche. It uses third person and stays grounded in concrete debugging scenarios.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions ('instrument the actual runtime path, reproduce the real issue, then inspect append-only JSONL logs') tied to specific domains, though phrased more as a process than discrete capabilities.	4 / 5
Completeness	Explicitly answers both what ('Use early when debugging a medium or hard bug... inspect append-only JSONL logs before deciding on a fix') and when ('Trigger this before extended TDD iteration when...'), with concrete trigger phrases and a clear skip condition.	5 / 5
Trigger Term Quality	Comprehensive natural trigger terms covering 'runtime state, ordering, persistence, streaming, concurrency, UI/manual reproduction, external services' plus 'red or newly passing test' and 'stack trace', matching phrasings a user would naturally say.	5 / 5
Distinctiveness Conflict Risk	Has a clear niche (instrument-and-reproduce debugging for runtime/ordering/concurrency bugs) with distinct triggers and an explicit skip-when-root-cause-is-proven boundary, minimizing conflict with general TDD or testing skills.	5 / 5
	Total	19 / 20 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: 8174f1c

Reviewed: ~16 hours 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.