systematic-debugging

4-phase root cause debugging: understand bugs before fixing.

Quality

63%

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 ./skills/software-development/systematic-debugging/SKILL.md

Quality

Content

77%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.

The content is an unusually actionable, well-sequenced debugging methodology: explicit phase gates, checklists, feedback loops, and executable commands throughout. Its weaknesses are redundancy between the Red Flags and Common Rationalizations sections plus motivational padding, and a monolithic single-file structure where a leaner core SKILL.md could push the loop recipes and Hermes integration details into reference files.

Suggestions

Merge the 'Red Flags' list and the 'Common Rationalizations' table into one anti-pattern section — they cover the same excuses twice ('One more fix attempt', 'Quick fix for now') and cost ~40 lines.

Drop or shrink the 'Real-World Impact' statistics block; the claims are unverifiable and motivational rather than instructional.

Move the Hermes tool integration snippets and the ten-recipe loop-construction catalog into references/ files (e.g. references/loops.md, references/hermes-tools.md), keeping a short ranked summary in SKILL.md with clear one-level-deep links.

Dimension	Reasoning	Score
Conciseness	The body is mostly imperative and prescriptive with little explanation of concepts Claude already knows, but there is unnecessary material that could be trimmed: the 'Red Flags' list and 'Common Rationalizations' table repeat the same excuses almost verbatim, and 'Real-World Impact' pads with unverifiable statistics ('First-time fix rate: 95% vs 40%'). This fits 'mostly efficient but includes some unnecessary explanation or could be tightened' rather than 4's 'minor instances'.	3 / 5
Actionability	The guidance is fully executable: concrete commands ('pytest tests/test_module.py::test_name -v', 'git log --oneline -10', a 100x flake-repro shell loop), ten specific loop-construction recipes ranked by preference, and a copy-paste-ready convention for tagging temporary debug logs ('[DEBUG-a4f2]'). Specific commands cover the common cases, matching the top anchor.	5 / 5
Workflow Clarity	The four phases are explicitly sequenced with 'You MUST complete each phase before proceeding to the next', a Phase 1 completion checklist with STOP gates, per-step verification ('Did it work? -> Phase 4 / Didn't -> form NEW hypothesis'), and the Rule of Three feedback loop that returns to Phase 1 on failure. This matches the anchor's 'explicit validation steps; feedback loops for error recovery; checklists'.	5 / 5
Progressive Disclosure	No bundle files exist (references/, scripts/, assets/ are absent), so everything is inline in a ~400-line SKILL.md. Section headers give it real structure, but content that would sit better in separate files — the ten-recipe loop-construction catalog, the Hermes tool-integration snippets, the rationalizations table — is inlined, and there are no one-level-deep references to move detail into. This fits 'some structure but could be better organized; content that should be separate is inline'.	3 / 5
	Total	16 / 20 Passed

Description

50%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.

The description is concise and states a clear 'what', but it omits any 'when to use' guidance and enumerates no concrete capabilities beyond 'root cause debugging'. It reads as a title-and-tagline rather than a trigger-rich description, capping completeness and trigger quality at the midpoint.

Suggestions

Add a 'Use when...' clause with concrete triggers, e.g. 'Use when a test fails unexpectedly, a bug reproduces in production, a fix has already failed once, or a flaky test needs investigation.'

Enumerate the phases or their outputs so the 'what' is specific, e.g. 'reproduce with a tight feedback loop, minimize the repro, rank falsifiable hypotheses, then fix the confirmed root cause.'

Include natural synonym terms users actually say ('bug', 'troubleshoot', 'test failure', 'flaky', 'investigate why') to improve trigger-term coverage and distinctiveness from adjacent skills.

Dimension	Reasoning	Score
Specificity	The description names the domain ("debugging") and one concrete activity ("root cause debugging") plus a structure hint ("4-phase"), but lists no specific actions or what the phases are. It fits 'names domain and 1-2 concrete actions' rather than 4, which requires several specific actions with only minor gaps, and is more concrete than the bare domain label of 2.	3 / 5
Completeness	The 'what' is clear ('4-phase root cause debugging: understand bugs before fixing') but there is no 'Use when...' clause or equivalent explicit trigger guidance, which per the judging guidelines caps completeness at 3. It is above 2 because the 'what' is stated clearly, not vaguely.	3 / 5
Trigger Term Quality	"root cause" and "debugging" are natural terms users would say, but common variations and synonyms ("bug", "troubleshoot", "test failure", "fix", "investigate") are missing. This matches 'some relevant keywords but missing common variations' rather than 4's 'good keyword coverage'.	3 / 5
Distinctiveness Conflict Risk	"Root cause debugging" carves out a methodological niche, but the description could still overlap with general debugging, troubleshooting, or TDD skills (the skill itself lists related_skills) and offers no distinct trigger phrases to disambiguate. It is somewhat specific but not the 'clear niche with distinct triggers' of 5 or the 'mostly distinct' of 4.	3 / 5
	Total	12 / 20 Passed

Validation

75%

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 — 12 / 16 Passed

Validation for skill structure

Criteria	Description	Result
metadata_version	'metadata.version' is missing	Warning
metadata_field	'metadata' should map string keys to string values	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
referenced_paths_exist	Referenced path issues: 1 missing	Warning

	Total	12 / 16 Passed

Repository: NousResearch/hermes-agent
Path: skills/software-development/systematic-debugging/SKILL.md
Commit: 68fa7e9

Reviewed: 3 days 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.