Skip to content
cccskills
FreePublished on GitHub

debug

Debug a bug or unexpected behavior systematically. Use when the user says "there's a bug", "this isn't working", "I'm getting an error", "help me debug", "why is this failing", "unexpected behavior", "test is failing", "something is broken", or describes behavior that doesn't match expectations - even if they don't say "debug".

The English summary is being prepared. Showing the original description.

See how to install

Files included (1)

  • SKILL.md3.7 KB

SKILL.md (original)

Review the instructions the agent will receive before you install.

Overview

Based on "The Pragmatic Programmer" by Andrew Hunt & David Thomas. Hunt & Thomas's debugging philosophy: debugging is a puzzle to be solved with evidence, not a crisis to be panicked through. The key discipline is don't guess. Form a hypothesis, predict what you'll see if the hypothesis is correct, test it, and observe. Repeat.

Their rubber duck principle: before asking for help, explain the problem out loud (to a rubber duck or anyone). The act of articulating often reveals the answer.

Workflow

Step 1: Reproduce the bug reliably

You cannot debug what you cannot reproduce.

  • What exact steps produce the bug? Document them.
  • Is it 100% reproducible or intermittent?
  • On which environments? (dev only, staging, prod?)
  • Since when? (what changed recently?)

If you can't reproduce it reliably, make that the first problem to solve.

Step 2: Understand the expected vs actual behavior

State explicitly:

  • Expected: what should happen?
  • Actual: what is happening?
  • Evidence: logs, error messages, screenshots

Do not skip this. Vague bug descriptions lead to fixing the wrong thing.

Step 3: Form a hypothesis

What is your best theory for why the actual differs from expected? Write it down. Debugging without a hypothesis is random exploration.

Step 4: Predict the evidence

If your hypothesis is correct, what will you see when you look at [specific thing]? Make a prediction before you look. This keeps you honest.

Step 5: Test the hypothesis

  • Add targeted logging or use a debugger to observe the predicted evidence
  • Change one thing at a time - not multiple
  • If the evidence matches: hypothesis confirmed, move to Step 6
  • If the evidence doesn't match: your hypothesis is wrong, go back to Step 3

Step 6: Fix the root cause (not the symptom)

Hunt & Thomas: fix the problem, not the symptom.

  • Symptom fix: catching an exception that shouldn't be thrown
  • Root cause fix: understanding why the exception is thrown and preventing it

Ask "why" five times before writing the fix.

Step 7: Verify the fix

  • Does the original reproduction case pass?
  • Do existing tests still pass?
  • Write a test that would have caught this bug originally

Step 8: Document the learning

What was the root cause? What made it hard to find? How could it be caught earlier next time?

Anti-Patterns

1. Guessing instead of hypothesizing Bad: Randomly changing things until it works. Good: Form a hypothesis. Predict evidence. Test. Observe. Either confirm or refute.

2. Fixing the symptom Bad: Adding a null check to stop the crash. Good: Understanding why null is reaching that point and preventing it at the source.

3. Changing multiple things at once Bad: "Let me try these 5 changes together." Good: One change at a time. Otherwise you don't know which change fixed it.

4. Not writing a regression test Bad: Fix the bug, move on. Good: Write a test that reproduces the bug before fixing it. The test passes after the fix. It lives in the suite forever.

Quality Checklist

  • Bug is reproducible with documented steps
  • Expected vs actual behavior stated explicitly
  • Hypothesis written down before testing
  • Evidence predicted before looking
  • One change at a time during investigation
  • Root cause identified (not just symptom)
  • Fix verified against original reproduction case
  • Regression test written

Reviews

No reviews yet. Tell others what you thought.

Comments

No login needed. Share how it worked for you, ask a question, or note where it did not run.

No comments yet. Be the first to write one.

Comments are published right away. Do not include personal information such as email addresses or phone numbers. Up to 2 URLs.

0 / 1,000 characters

This form is protected by reCAPTCHA, and the Google Privacy Policy and Terms of Service apply.

More skills from this repository

Rate any product, feature, or experience on the 11-star scale (Brian Chesky's Airbnb thought experiment). Use when user says "rate this experience", "11-star", "star rating", "experience audit", "how good is this", "experience rating", "product audit", "quality assessment", or wants to evaluate product quality and identify improvement paths. Also trigger when user wants to benchmark a feature, assess where a product stands, or map out what "great" looks like - even if they don't explicitly say "11-star".

The English summary is being prepared. Showing the original description.

qa-aman/claude-skills21Updated Oct 19, 2026

Generate A/B copy variants grounded in Eugene Schwartz's awareness and market-sophistication stages and John Caples' tested-headline discipline. Every variant declares its angle, the awareness stage it targets, and a falsifiable hypothesis, and the skill recommends which pair to test first and what delta counts as signal. Use when the user says "A/B test this", "write variants", "give me options", "test different angles", "copy variants", "ab copy", "test this headline", "multiple versions", "which version is better", or wants to test copy before publishing. For reviewing copy that already exists, see copy-review. For sample size and stopping rules, see growth-experiment. For diagnosing a page rather than its words, see page-cro. For full paid ad sets by platform, see ad-campaign-writer.

The English summary is being prepared. Showing the original description.

qa-aman/claude-skills21Updated Oct 19, 2026

Design statistically rigorous experiments to test data science hypotheses. Use when the user says "design an A/B test", "run an experiment", "test this hypothesis", "is this difference significant", "how many samples do I need", "randomized controlled trial", "causal inference", "uplift test", "holdout group", "significance test", "power calculation", "avoid p-hacking", or needs to determine whether an observed effect is real before making a product or model decision. For lean build-measure-learn product experiments without the statistics, use experiment-design instead.

The English summary is being prepared. Showing the original description.

qa-aman/claude-skills21Updated Oct 19, 2026

Write measurable acceptance criteria for requirements or user stories. Use when the user says "write acceptance criteria", "definition of done", "how do we test this", "fit criteria", "given when then", "Gherkin scenarios", "what does done look like", "testable conditions", "how will we know this works" - even if they don't explicitly say "acceptance criteria".

The English summary is being prepared. Showing the original description.

qa-aman/claude-skills21Updated Oct 19, 2026

Build a strategic account plan for winning, retaining, or expanding a named account. Use when the user says "build an account plan", "strategic account planning", "how do I grow this account", "account expansion strategy", "whitespace analysis", "QBR prep", "key account review", "map the stakeholders in this account", "land and expand plan", "how do I break into [company]", or wants a structured strategy for a specific account.

The English summary is being prepared. Showing the original description.

qa-aman/claude-skills21Updated Oct 19, 2026

Write paid ad copy for LinkedIn, Google, Meta, and YouTube. Produces multiple variants per platform, each targeting a different Eugene Schwartz awareness level and Cialdini persuasion principle. Use when the user asks for ad copy, ad variants, "write LinkedIn ads", Google ads, Meta ads, paid social copy, ad headlines, or wants creative for a paid campaign. Reads brand voice, ICP, and positioning from knowledge/. For organic social posts, see linkedin-post or social-calendar. For the landing page the ad points at, see landing-page-writer. For testing variants, see ab-copy-writer.

The English summary is being prepared. Showing the original description.

qa-aman/claude-skills21Updated Oct 19, 2026

See all skills by qa-aman

Report a problem with this skill