CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

structured-debugging

Hypothesis-driven debugging methodology for hard bugs. Use this skill whenever you're investigating non-trivial bugs, unexpected behavior, flaky tests, or tracing issues through complex systems. Activate proactively when debugging requires more than a quick glance — especially when the first attempt at a fix didn't work, when behavior seems "impossible", or when you're tempted to blame an external system (model, API, library) without evidence.

Quality

77%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.qwen/skills/structured-debugging/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

70%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 disciplined, well-sequenced debugging methodology with strong validation checkpoints and a concrete exit template — its workflow clarity is exemplary. Weaknesses are repetition of the data-vs-code-paths theme across sections and a worked-example reference that points to a nonexistent file.

Suggestions

Add the missing 'examples/headless-bg-agent-empty-stdout.md' file (or remove the 'Worked examples' section) so the body's only external reference resolves.

Consolidate the three separate statements of 'instrument data, not code paths' (step 2, the failure-modes section, and 'Persistent State') into one authoritative section to cut roughly 20-30 lines.

Fix the typo 'does does it hang or exit cleanly?' and turn the environment-diff catalogue in 'Reframing the user's report' into a concrete checklist (TTY vs pipe, locale, env vars, prior state).

DimensionReasoningScore

Conciseness

The body is mostly efficient — the good/bad hypothesis example, the instrumentation traps list, and the exit-criteria template all earn their tokens — but themes repeat: 'instrument data, not code paths' appears in step 2, again as a failure mode, and again in 'Persistent State'; 'blaming external systems' appears in the description-echo and its own section. This matches anchor 3 ('mostly efficient but includes some unnecessary explanation or could be tightened'); it is not a 2 because there is no padding explaining concepts Claude already knows, and not a 4 because consolidating the repeated data-vs-code-paths material would meaningfully shrink the file.

3 / 5

Actionability

The guidance is concrete and executable for an instruction-only skill: a worked good/bad hypothesis pair, the 2-3 instrumentation points rule with a self-check question, an enumerated list of data-capture traps, and a copy-ready exit template ('Root cause: [specific mechanism] / Evidence: [specific log lines] / Fix: ...'). Per the rubric's scoring notes, absence of code is not penalized when guidance is actionable; it is not a 5 because some directives remain abstract ('catalogue what differs between their environment and yours' has no checklist or example) and there is a typo ('does does it hang').

4 / 5

Workflow Clarity

The six-step cycle (Hypothesize → Design Instrumentation → Verify Data Collection → Run and Observe → Document Findings → Iterate) is clearly sequenced with explicit validation checkpoints: step 3 exists solely to verify data capture, step 4 mandates believing data over theory ('When the data contradicts your hypothesis, believe the data'), and the exit section requires evidence-backed root-cause confirmation before any fix, with a re-verify clean run after applying it. There is also an escalation checkpoint ('If you're not making progress after 3 rounds, step back and question your assumptions'). This matches anchor 5's explicit validation steps, feedback loops, and checklists; it is clearly above anchor 4's 'minor validation gaps'.

5 / 5

Progressive Disclosure

Section structure is good (numbered cycle, failure modes, exit criteria), but the single external reference — 'examples/headless-bg-agent-empty-stdout.md' — points to a file that does not exist in the bundle (no examples/, references/, scripts/, or assets/ directories are present). A clearly signaled but broken reference means navigation fails at exactly the point a reader would follow it, fitting anchor 3 ('some structure but could be better organized; references present but not clearly signaled' — here, not usable). It is not a 2 because the body is not an inlined wall of text that belongs in separate files, and not a 4 because a dead link is more than a minor organization gap.

3 / 5

Total

15

/

20

Passed

Description

73%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 well-constructed description with explicit, concrete trigger conditions and a clear what/when structure. Its main weaknesses are second-person voice (which costs specificity per the rubric) and generic action verbs where concrete methodology steps could be named.

Suggestions

Rewrite in third person ('Guides hypothesis-driven debugging of hard bugs...' instead of 'whenever you're investigating...') to avoid the rubric's second-person specificity penalty.

Replace generic verbs like 'investigating' and 'tracing issues' with the concrete techniques the skill teaches (e.g., 'form testable hypotheses, instrument decision points, gate fixes on observed evidence').

Add common user phrasings such as 'root cause', 'can't reproduce', or 'why is this happening' to broaden natural trigger coverage.

DimensionReasoningScore

Specificity

The description names the domain ('Hypothesis-driven debugging methodology for hard bugs', 'tracing issues through complex systems') but the actions themselves are minimal and generic — 'investigating', 'tracing' — with no list of concrete techniques (e.g., instrument-observe-iterate, side-note journal, evidence-gated fixes). This lands at anchor 3 ('names domain and 1-2 concrete actions'), but the judging guideline mandates a 1-point penalty for second-person voice ('whenever you're investigating', 'you're tempted to blame'), bringing it to 2. It is not a 1 because the domain and methodology framing are concrete, not pure abstraction.

2 / 5

Completeness

Both questions are answered explicitly and concretely: what it does ('Hypothesis-driven debugging methodology for hard bugs') and when to use it ('Use this skill whenever you're investigating non-trivial bugs, unexpected behavior, flaky tests...' plus 'Activate proactively when...'). This matches the anchor-5 good example structure of capability statement followed by explicit 'Use when' trigger clauses; it is not a 4 because the 'when' is not merely present but highly specific with multiple concrete trigger conditions.

5 / 5

Trigger Term Quality

Strong natural keyword coverage: 'non-trivial bugs', 'unexpected behavior', 'flaky tests', 'tracing issues', 'first attempt at a fix didn't work', 'behavior seems impossible' — phrases a user would plausibly say verbatim. It falls short of anchor 5 because common variations like 'root cause', 'can't reproduce', 'regression', or 'why is this happening' are absent, leaving a few natural entry terms missing.

4 / 5

Distinctiveness Conflict Risk

The trigger conditions ('first attempt at a fix didn't work', 'behavior seems impossible', 'tempted to blame an external system without evidence') are distinctive and unlikely to fire for unrelated skills. It is not a 5 because 'debugging' broadly overlaps with code-review, testing, and error-triage skills, so a closely related skill in the same library could compete for the same queries; it is well above a 3 because the specific escalation triggers carve out a clear niche.

4 / 5

Total

15

/

20

Passed

Validation

100%

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

QwenLM/qwen-code

Path

.qwen/skills/structured-debugging/SKILL.md

Reviewed

Table of Contents

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.