agentleFS
Sign inStart free
captain-corgicaptain-corgi/marketplace-website/.claude/skills/debugging/SKILL.md

Debugging

Skill0 starsChanged 11 months agoMITView on GitHub

Systematic debugging framework ensuring root cause investigation before fixes. Includes four-phase debugging process, backward call stack tracing, multi-layer validation, and verification protocols. Use when encountering bugs, test failures, unexpected behavior, performance issues, or before claiming work complete. Prevents random fixes, masks over symptoms, and false completion claims.

116 other projects use a version of this, 4 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use ssr, remove-ai-slops and 2 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • JetBrainsSkill

    ssr

    Guide for using Structural Search and Replace in IntelliJ. Use when creating or modifying SSR inspections or search patterns.

    Also in 3 projects that use this

  • DevNewbie1826Skill

    remove-ai-slops

    Remove AI-generated code slop from branch changes or an explicit file list while preserving behavior, including junk tests (prose pins, source greps, copied inventories, mock echoes), each proven by its class rule before a cut. Use when asked to remove slop, clean AI code, deslop, clean up generated code, strip slop, prune junk tests, or review generated-code cleanup. Start by locking behavior with regression tests, then use the category and workflow references.

    Also in 3 projects that use this

  • mrgoonieSkill

    aesthetic

    Create aesthetically beautiful interfaces following proven design principles. Use when building UI/UX, analyzing designs from inspiration sites, generating design images with ai-multimodal, implementing visual hierarchy and color theory, adding micro-interactions, or creating design documentation. Includes workflows for capturing and analyzing inspiration screenshots with chrome-devtools and ai-multimodal, iterative design image generation until aesthetic standards are met, and comprehensive design system guidance covering BEAUTIFUL (aesthetic principles), RIGHT (functionality/accessibility), SATISFYING (micro-interactions), and PEAK (storytelling) stages. Integrates with chrome-devtools, ai-multimodal, media-processing, ui-styling, and web-frameworks skills.

    Also in 4 projects that use this

  • DevNewbie1826Skill

    programming

    MUST USE for work on Python, Rust, TypeScript, JavaScript, or Go source files and project manifests, and whenever a test or spec file is written, reshaped, reviewed, or deleted. Triggers: write or edit code; add, change, or delete a test; test authoring gate; junk tests; new project; Go HTTP service (gin lane); Bubble Tea TUI; CJK IME; Connect-Go RPC; sqlc or pgx; branded IDs; exhaustive matching; unsafe Rust; Miri; oversized file; refactoring; logging, log levels, structured logging, or observability; arena, allocator, bumpalo, const fn, const generics, compile-time programming, zero-allocation APIs, bitfields, repr, scope guards, errdefer-style cleanup, Zig-like patterns, zero-copy parsing, packed data, or FFI; Rust public API design or macros.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

7 rules. 0 are common, 7 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 101 edited versions we read keep these.

  • 7

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Always use for: Test failures, bugs, unexpected behavior, performance issues, build failures, integration problems, before claiming work …

    line 20
  2. Distinctive:

    Technique: When error appears deep in execution, trace backward level-by-level until finding source where invalid data originated.

    line 42
  3. Distinctive:

    Load when: After finding root cause, need to add comprehensive validation

    line 54
  4. Distinctive:

    Run verification commands and confirm output before claiming success.

    line 58
  5. Distinctive:

    Iron law: NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

    line 60
  6. Distinctive:

    Run the command. Read the output.

    line 62
  7. Distinctive:

    Stop and follow process if thinking:

    line 77

“Common” is measured: kept by at least 6 in 10 of the 101 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Debugging

Comprehensive debugging framework combining systematic investigation, root cause tracing, defense-in-depth validation, and verification protocols.

Core Principle

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

Random fixes waste time and create new bugs. Find the root cause, fix at source, validate at every layer, verify before claiming success.

When to Use

Always use for: Test failures, bugs, unexpected behavior, performance issues, build failures, integration problems, before claiming work complete

Especially when: Under time pressure, "quick fix" seems obvious, tried multiple fixes, don't fully understand issue, about to claim success

The Four Techniques

1. Systematic Debugging (references/systematic-debugging.md)

Four-phase framework ensuring proper investigation:

  • Phase 1: Root Cause Investigation (read errors, reproduce, check changes, gather evidence)
  • Phase 2: Pattern Analysis (find working examples, compare, identify differences)
  • Phase 3: Hypothesis and Testing (form theory, test minimally, verify)
  • Phase 4: Implementation (create test, fix once, verify)

Key rule: Complete each phase before proceeding. No fixes without Phase 1.

Load when: Any bug/issue requiring investigation and fix

2. Root Cause Tracing (references/root-cause-tracing.md)

Trace bugs backward through call stack to find original trigger.

Technique: When error appears deep in execution, trace backward level-by-level until finding source where invalid data originated. Fix at source, not at symptom.

Includes: scripts/find-polluter.sh for bisecting test pollution

Load when: Error deep in call stack, unclear where invalid data originated

3. Defense-in-Depth (references/defense-in-depth.md)

Validate at every layer data passes through. Make bugs impossible.

Four layers: Entry validation → Business logic → Environment guards → Debug instrumentation

Load when: After finding root cause, need to add comprehensive validation

4. Verification (references/verification.md)

Run verification commands and confirm output before claiming success.

Iron law: NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

Run the command. Read the output. Then claim the result.

Load when: About to claim work complete, fixed, or passing

Quick Reference

Bug → systematic-debugging.md (Phase 1-4)
  Error deep in stack? → root-cause-tracing.md (trace backward)
  Found root cause? → defense-in-depth.md (add layers)
  About to claim success? → verification.md (verify first)

Red Flags

Stop and follow process if thinking:

  • "Quick fix for now, investigate later"
  • "Just try changing X and see if it works"
  • "It's probably X, let me fix that"
  • "Should work now" / "Seems fixed"
  • "Tests pass, we're done"

All mean: Return to systematic process.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free