debugging

A structured debugging guide for finding the proven cause of difficult, intermittent, cross-layer, or regression bugs before changing code.

In plain words
What is it for?
Use it to diagnose unknown bugs, investigate failures that normal debugging has not solved, identify the first incorrect result, and apply a small verified fix with a regression test when requested.
Why use it?
It prevents guesswork and fixes based only on symptoms. It helps narrow the issue using reproduction steps, logs, program state, and comparisons with working behavior.

Skill for Claude CodeCodex

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add skills/kleosr/kleosrules/debugging
Any agent
npx skills add kleosr/kleosrules --skill debugging
Clone the repo
git clone --depth 1 https://github.com/kleosr/kleosrules

Made for: Claude Code, Codex.

Per session 46 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 396 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00046 $0.00396
Opus 5 $0.00023 $0.00198
Sonnet 5 $0.00009 $0.00079
Haiku 4.5 $0.00005 $0.00040

Measured 2d ago against content hash a0ca274a35c6, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

debugging scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

shared/skills/debugging/SKILL.md · 48 lines

What it actually says

Bug hunt

No thin .mdc. This skill is the debugging roof.

Prove the cause; do not change code to generate hypotheses.

Mode

  • Diagnose/assess → findings only.
  • Fix requested → investigate first, then apply the smallest proven fix.

Workflow

  1. State the exact symptom, expected behavior, scope, and known-good baseline.
  2. Reproduce with the smallest deterministic case. Cannot reproduce → report the missing signal and stop.
  3. Read the complete error, logs, stack, inputs, and relevant state.
  4. Classify the likely boundary: logic, data, state, concurrency, cache, configuration, contract, environment, or integration.
  5. Trace backward from the first wrong observable value; compare failing and working paths.
  6. Write one falsifiable hypothesis and gather evidence for or against it.
  7. Inspect callers, contracts, and recent history when evidence points there.
  8. Prove the root cause before editing. After three misses, send STUCK with evidence and ask for the missing information.
  9. If authorized, fix one cause, add a regression test, and rerun the original reproduction plus affected TOOLCHAIN checks.

Guardrails

  • No catch/sleep/retry, mock, assertion, or test weakening to hide failure.
  • No simultaneous fixes for competing hypotheses.
  • Cross-boundary symptoms use NOW.md (/now).
  • Preserve logs/artifacts needed to explain the result; never expose secrets.

Report

Symptom → proven cause → evidence → changed or recommended fix → regression and original-repro results. Label anything unverified.

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 2d ago First seen · 48 lines · 46 tokens per session scan A a0ca274a35c6

Subscribe to this mod's changes

debugging is a skill published in the GitHub repository kleosr/kleosrules (2 stars, last pushed 2d ago), licensed MIT. It adds 46 tokens to every session and 396 once invoked, about $0.0002 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Related

Other skills, from other repositories

coding-agents-hooks-authoring

To author, register, and test Rosetta hooks, add a SemanticKind, or debug a hook that won't fire.

griddynamics/rosetta · 31 tokens

agentic-dns

Agentic AI-native multi-tier DNS routing, live packet tracing, and failover bypass engine for Pi-hole, CoreDNS, dnsdist, Unbound, Stubby, DNSCrypt-Proxy, and VPN DNS.

dedsecorg/agentic-dns · 48 tokens

diagnose

Diagnose your Claude Code hooks setup. Checks which hooks are active, verifies permissions, and identifies common configuration issues.

yurukusa/claude-code-hooks · 26 tokens

audit-credentials

Audits local credential setup for security compliance and produces a report. Use this skill when the user needs to: Check whether their credentials are properly stored and not leaking Validate credential rotation age against their policy Scan shell history, dotfiles, and git repos for exposed credentials Check file…

osloer-industries/vakt · 142 tokens

142-java-functional-programming

Use when you need to apply functional programming principles in Java — including writing immutable objects and Records, pure functions, functional interfaces, lambda expressions, Stream API pipelines, Optional for null safety, function composition, higher-order functions, pattern matching for instanceof and switch…

jabrena/cursor-rules-examples · 96 tokens

144-java-data-oriented-programming

Use when you need to apply data-oriented programming best practices in Java — including separating code (behavior) from data structures using records, designing immutable data with pure transformation functions, keeping data flat and denormalized with ID-based references, starting with generic data structures…

jabrena/cursor-rules-examples · 88 tokens