CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

loop-diagnosis

Diagnose and fix stalled agent loops using the joelclaw CLI. Use when loops appear stuck, stories aren't progressing, or the event chain broke. Triggers on "loop stalled", "why isn't the loop progressing", "diagnose loops", "fix stuck loop", "loop not moving", "what happened to the loop", "stories stuck at pending", or any request to debug loop infrastructure.

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

SKILL.md
Quality
Evals
Security

Quality

Content

88%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 excellent diagnostic skill body: fully executable commands, a diagnosis-to-fix lookup table, a clear escalation workflow with verification, and a system-specific event-chain map that assumes Claude's competence. The main issues are two sections describing future/planned infrastructure rather than actionable diagnosis, and cross-references using non-portable absolute paths.

Suggestions

Trim the "Observability Patterns" (Future watchdog) and "Making Loops More Resilient" sections to one or two lines of context, or move them to a separate reference doc — they describe planned infrastructure, not diagnosis steps.

Replace absolute machine-specific cross-reference paths (/Users/joel/..., /Users/joel/Vault/...) with portable relative paths so the links resolve wherever the skill bundle is installed.

Optionally state explicitly that `--fix` and `loop restart` mutate state (clear claims, re-fire events, restart deployments) before the Quick Commands block, so the destructive nature of the auto-fix flag is visible up front.

DimensionReasoningScore

Conciseness

The body is lean overall — tables, terse bullets, and executable commands with no explanation of concepts Claude already knows. However, the "Observability Patterns" section (watchdog marked "Future") and "Making Loops More Resilient" ("Solutions being implemented") describe planned infrastructure the diagnosing agent cannot act on. This matches anchor 4 (efficient with minor instances that could be trimmed); it is above anchor 3 because padding is limited to those two sections, and below anchor 5 because those sections do not earn their tokens for the diagnosis task.

4 / 5

Actionability

Quick Commands gives copy-paste-ready invocations ("joelclaw loop diagnose all -c", "--fix", JSON mode), the failure-modes table maps every diagnosis to root cause and specific auto-fix, and the manual session includes an executable curl+python one-liner for worker health. This matches anchor 5 (fully executable, copy-paste ready, covers common cases); no gaps found.

5 / 5

Workflow Clarity

The "Manual: The Diagnostic Session" section is a numbered 1-5 sequence with an explicit validation checkpoint ("Verify fix worked (wait ~30s for plan to fire)"), conditional escalation ("If still stuck, check worker"), and a final fallback (full restart). Feedback loops are present even though --fix/restart are risky operations, so the destructive-operation cap does not apply. This matches anchor 5; not anchor 4 because validation and error-recovery steps are explicit rather than minor-gapped.

5 / 5

Progressive Disclosure

No bundle files exist; the single ~120-line document is well-sectioned with clear headers, appropriate for a skill of this scope. However, the Cross-References section points to machine-specific absolute paths (/Users/joel/.pi/agent/skills/..., /Users/joel/Vault/docs/...) that will not resolve outside the author's machine. This matches anchor 4 (good structure, minor organization gaps); it is above anchor 3 because structure and sectioning are solid, and below anchor 5 because the cross-references are broken as written.

4 / 5

Total

18

/

20

Passed

Description

86%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 description that explicitly covers what the skill does and when to use it, with an unusually comprehensive set of natural trigger phrases. The only weaknesses are that the capability summary stops at two generic verbs (diagnose, fix) without hinting at the concrete checks or failure modes, and slight overlap risk with sibling loop-monitoring skills.

Suggestions

Briefly enumerate one or two concrete diagnostic capabilities (e.g., "runs 6 checks across Redis state, worktrees, Inngest runs, and worker health, and auto-fixes broken event chains") to lift specificity beyond two generic verbs.

Disambiguate from the sibling loop-nanny skill with a contrast clause such as "for diagnosing and repairing stalled loops, not for routine monitoring or cleanup" to reduce overlap risk on progress-related trigger phrases.

DimensionReasoningScore

Specificity

"Diagnose and fix stalled agent loops using the joelclaw CLI" names the domain, tool, and two concrete actions (diagnose, fix) but does not enumerate what diagnosis covers (the checks or failure modes). This matches anchor 3 (domain plus 1-2 concrete actions, not comprehensive); it is above anchor 2 because the actions are specific rather than generic, and below anchor 4 because it does not list several specific actions.

3 / 5

Completeness

It explicitly answers both "what" ("Diagnose and fix stalled agent loops using the joelclaw CLI") and "when" ("Use when loops appear stuck, stories aren't progressing, or the event chain broke. Triggers on ..."), with concrete trigger phrases. This matches anchor 5; it is not anchor 4 because the "when" guidance is explicit and specific rather than improvable.

5 / 5

Trigger Term Quality

The trigger list covers comprehensive natural phrasings and synonyms users would actually say: "loop stalled", "why isn't the loop progressing", "fix stuck loop", "loop not moving", "what happened to the loop", "stories stuck at pending", "debug loop infrastructure". This matches anchor 5 (comprehensive coverage of natural terms including synonyms); anchor 4 would require a few natural terms to be missing, which is not the case.

5 / 5

Distinctiveness Conflict Risk

The niche (stalled-loop diagnosis via joelclaw) is clear and triggers are distinct, but phrases like "why isn't the loop progressing" and "loop not moving" could plausibly also match a loop-monitoring skill (loop-nanny), giving minor overlap risk with closely related skills. This matches anchor 4; not anchor 5 because of that adjacent-skill overlap, and not anchor 3 because the domain and triggers are otherwise quite specific.

4 / 5

Total

17

/

20

Passed

Validation

93%

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

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

relative_links

Relative link issues: 4 suspicious

Warning

Total

15

/

16

Passed

Repository

joelhooks/joelclaw

Path

skills/loop-diagnosis/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.