debugging-patterns

A step-by-step method for finding and fixing software bugs by reproducing them, measuring what happens, and tracing data through the program.

In plain words
What is it for?
It helps investigate null values, asynchronous timing problems, stale state, missing imports, wrong names, cache issues, and other common failures.
Why use it?
It replaces guesswork with a repeatable process for narrowing down the cause of an error.

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/subhansh-dev/agent-maxxing/debugging-patterns
Any agent
npx skills add subhansh-dev/agent-maxxing --skill debugging-patterns
Clone the repo
git clone --depth 1 https://github.com/subhansh-dev/agent-maxxing

Made for: Claude Code, Codex.

Per session 26 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 524 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.00026 $0.00524
Opus 5 $0.00013 $0.00262
Sonnet 5 $0.00005 $0.00105
Haiku 4.5 $0.00003 $0.00052

Measured yesterday against content hash 09b72ca9900d, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

debugging-patterns 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 yesterday.

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.

engineering/debugging-patterns/SKILL.md · 60 lines

How it starts

The opening of the file, as written. The whole thing — 60 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Debugging Patterns — How to Fix Things

The Debugging Chain

When you hit a bug:

  1. Read the error message completely. All of it. Don't skim.
  2. Reproduce it. Run the code. Hit the error. See it yourself.
  3. Bisect. Comment out half the code. Does it still happen? Binary search.
  4. Add logging. Print the state at each step. Don't guess — measure.
  5. Trace the flow. Follow the data from input to output. Where does it go wrong?
  6. Check the obvious. Typos, wrong variable names, missing imports, stale caches.
  7. Search for it. Someone else probably hit this. Stack Overflow, GitHub issues, docs.
  8. Try the simplest fix first. Don't refactor the whole system for a typo.
  9. If you're going in circles, stop. Explain what you've tried and why each attempt failed.

Common Bug Categories

Null/Undefined

  • Check if the value is actually defined before using it
  • Trace where it comes from — is it async? Is it cached?
  • Add a guard: if (!value) return or value ?? fallback

Async/Timing

  • Is something racing? Add await or locks
  • Is the order wrong? Log timestamps
  • Is the callback firing twice? Check event listener cleanup

State

  • Is the state stale? Log it before and after
  • Is it shared between instances? Check for singleton issues
  • Is it being mutated unexpectedly? Use immutable patterns

Environment

  • Is it a different Node/Python version?
  • Is it a different OS? (path separators, line endings)
  • Is it a different environment variable?
  • Is it a cached build? Clean and rebuild.

The "Rubber Duck" Technique

Explain the problem out loud (or in a comment). The act of articulating it often reveals the solution. If you can't explain it simply, you don't understand it yet.

When to Ask for Help

After you've:

  1. Read the error completely
  2. Reproduced it
  3. Tried the obvious fixes
  4. Added logging
  5. Searched for similar issues
  6. Still stuck

Then ask. Include: what you tried, what happened, what you expected.

Read the full file on GitHub · 60 lines

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. yesterday First seen · 60 lines · 26 tokens per session scan A 09b72ca9900d

Subscribe to this mod's changes

debugging-patterns is a skill published in the GitHub repository subhansh-dev/agent-maxxing (2 stars, last pushed 1mo ago), licensed MIT. It adds 26 tokens to every session and 524 once invoked, about $0.0001 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.