CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

diagnosing-bugs

Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.

Quality

89%

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

The canonical home for this skill is diagnosing-bugs in mattpocock/skills

SKILL.md
Quality
Evals
Security

Quality

Content

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

An exceptionally tight process skill: it converts debugging from vibes into a gated, checklisted pipeline built around one core discipline (a tight red-capable feedback loop), with concrete tooling, formats, and a real HITL script. The only structural nit is that the loop-construction catalogue is kept fully inline rather than externalized, which is a defensible but imperfect disclosure decision.

DimensionReasoningScore

Conciseness

The body is lean and assumes Claude's competence throughout — e.g. "**Failing test** at whatever seam reaches the bug: unit, integration, e2e" and "**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep" convey maximal instruction in minimal tokens. It never explains concepts Claude already knows; even the aphoristic lines ("Untagged logs survive; tagged logs die") are compressed load-bearing guidance, not padding.

5 / 5

Actionability

Guidance is concrete and executable: ten specific loop-construction strategies naming exact tools (curl, Playwright/Puppeteer, `git bisect run`), a copy-paste hypothesis format ("If <X> is the cause, then <changing Y> will make the bug disappear"), a concrete log-tag convention, and a real, runnable template at `scripts/hitl-loop.template.sh` (verified to exist). The one-command completion criterion gives an unambiguous, checkable exit condition for Phase 1.

5 / 5

Workflow Clarity

Six phases are strictly sequenced with explicit gating checkpoints ("No red-capable command, no Phase 2", "Do not proceed until you have reproduced **and** minimised") and per-phase checklists. The workflow is itself a feedback loop (red loop → minimise → hypothesise → instrument → watch test fail/pass → re-run loop), and Phase 6's cleanup checklist (re-run loop, grep the DEBUG prefix, state the correct hypothesis in the commit message) provides end-to-end validation.

5 / 5

Progressive Disclosure

Good structure: the single bundle file (`scripts/hitl-loop.template.sh`) is clearly signaled at its point of use, is one level deep, and exists; section headers make the ~130-line body navigable. The inline 10-item "Ways to construct one" list is borderline content that could live in a reference file, and no references/ split exists for it — a minor organization gap that keeps this just below the ideal split.

4 / 5

Total

19

/

20

Passed

Description

78%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 concise, third-person description with an explicit and well-phrased 'Use when' trigger clause that clearly answers both what and when. Its main weakness is that the 'what' summarizes the skill as a single process rather than naming its concrete capabilities, slightly understating what the skill does.

Suggestions

Name one or two concrete capabilities in the 'what' clause, e.g. "Builds a failing repro loop, ranks hypotheses, instruments, and lands a regression-tested fix for hard bugs and performance regressions."

Add a couple of missing natural trigger synonyms such as "crashes", "errors", or "not working" to the 'Use when' clause to broaden natural-language matching.

Tighten distinctiveness by scoping the triggers toward the skill's hard-bug discipline (e.g. "for bugs that resist a first-pass fix") to reduce overlap with routine error-triage skills.

DimensionReasoningScore

Specificity

"Diagnosis loop for hard bugs and performance regressions" names the domain and one concrete action (a structured diagnosis loop), matching the anchor for 1–2 concrete actions that aren't comprehensive. It does not list the skill's several specific capabilities (repro loops, minimisation, hypothesis ranking, instrumentation, regression test), so it falls below the several-actions anchor of 4.

3 / 5

Completeness

Both halves are explicit: the what is "Diagnosis loop for hard bugs and performance regressions" and the when is a full 'Use when' clause with concrete trigger phrases ("the user says \"diagnose\"/\"debug this\", or reports something broken/throwing/failing/slow"). This matches the anchor that clearly answers both what and when with concrete triggers.

5 / 5

Trigger Term Quality

Natural user phrases are well covered: "diagnose", "debug this", "broken", "throwing", "failing", "slow" — exactly what a user with a bug would say. A few common variations ("crash", "error", "not working") are missing, which keeps it just below comprehensive synonym coverage.

4 / 5

Distinctiveness Conflict Risk

"Hard bugs and performance regressions" carves a clear niche distinct from ordinary code-writing skills, and the quoted triggers are specific. Minor overlap remains with closely related skills (generic test-fix or error-triage skills would also fire on "broken"/"failing"), so it is mostly distinct rather than minimal-conflict.

4 / 5

Total

16

/

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

tonykay/transcriber

Path

.agents/skills/diagnosing-bugs/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.