Claude Skill

debug

Debug errors, test failures, incorrect output, browser failures, intermittent bugs, and performance regressions through a tight red/green diagnosis loop. Use when behavior is broken, failing, flaky, slow, or unexplained.

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Download kriscard-skills-skills_dev_debug-08395f4.zip · 2 KB

Install

skills CLI npx skills add https://github.com/kriscard/Skills/tree/main/skills/dev/debug
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install kriscard-skills@llmmart
Git git clone https://github.com/kriscard/Skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole kriscard/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Debug

Build a tight, red-capable feedback loop before changing code. Then minimize, test falsifiable hypotheses, fix the root cause, and drive the same loop green.

1. Establish the symptom safely

Capture the user's exact observable symptom: error, wrong output, UI state, failed request, or measured latency. Record the triggering input, environment, and expected versus actual behavior.

Redact secrets before displaying or saving evidence:

  • Replace credentials, tokens, cookies, authorization headers, and personal data with <REDACTED>.
  • Record environment-variable names and presence by default, not values.
  • Keep credentials in the environment when building reproduction scripts.

Complete when: the symptom and expected behavior are precise enough that the final verification can distinguish fixed from unfixed without relying on judgment.

2. Build a tight red loop

Create one command or agent-runnable action sequence that exercises the user's exact symptom and returns an unambiguous pass/fail result. Prefer, in order, an existing failing test, a focused test, an HTTP or CLI script, a browser automation flow, or a replay of captured input.

For browser-visible or interaction bugs, invoke the installed agent-browser skill. Use it to drive the reproduction and capture relevant DOM state, console or page errors, network evidence, screenshots, traces, or video. Keep authentication human-controlled or in its auth vault.

Run the loop at least once and show the invocation and redacted failing signal. A tight loop is:

  • Red-capable: fails on the user's exact symptom, not a nearby error.
  • Deterministic: returns the same verdict, or a measured and pinned failure rate.
  • Fast: cheap enough to run after every experiment.
  • Agent-runnable: runs unattended whenever automation can reach the behavior.

For intermittent bugs, measure a baseline failure rate and raise it through repeated runs, controlled timing, concurrency, load, or replayed input. Record the conditions and sample size so the same experiment can be repeated after the fix.

If no useful loop can be built, stop and list what was tried. Request the missing environment access, a redacted HAR/log/trace/recording, or permission for temporary production instrumentation. Use a structured human-driven loop only when automation cannot perform an irreducibly human action such as 2FA, biometrics, or physical-device interaction.

Complete when: one already-run command or action sequence is red-capable, repeatable, and fast enough to guide diagnosis.

3. Reproduce and minimize

Run the loop until the failure is understood at the observable level. Shrink inputs, steps, config, data, and dependencies one at a time; rerun after every cut and retain only what keeps the loop red. For intermittent bugs, preserve the pinned conditions and report the measured failure rate rather than claiming determinism.

Complete when: the smallest practical scenario still produces the exact symptom, and its invocation, inputs, conditions, and failure signal are recorded.

4. Rank falsifiable hypotheses

Generate 3–5 plausible root-cause hypotheses before testing any one of them. For each, record:

  • supporting evidence;
  • contradicting or missing evidence;
  • the observation predicted if it is true;
  • the cheapest experiment that distinguishes it from the alternatives.

Rank by explanatory power and test cost. Discard or sharpen any hypothesis that makes no falsifiable prediction.

Complete when: the hypotheses are ranked and the next experiment has a predicted result that can support or reject one or more of them.

5. Run one-variable experiments

Change one variable at a time and map every probe to a prediction from Phase 4. Use focused logging, a debugger, config or input substitution, dependency isolation, or history comparison as the hypothesis requires. Inspect recent changes, versions, configuration, service state, and timing only when they distinguish live hypotheses.

Use git bisect only with a known-good revision and the red/green loop as its test; restore the original repository state with git bisect reset afterward. Keep instrumentation temporary and redact its output.

After each experiment, record the command, result, and which hypotheses gained or lost support. Update the ranking before choosing the next experiment.

Complete when: evidence identifies the causal mechanism and explains the observed symptom; correlation or a disappearing symptom alone is insufficient.

6. Prove, fix, and clean up

When a stable test seam exists, add a regression test before the fix and run it red on the reported symptom. Otherwise, state why the reproduction loop is the appropriate verification artifact. Apply the smallest change that addresses the causal mechanism.

Run the regression test or original loop green. For intermittent bugs, use the same conditions and sample size as the baseline. Run the relevant broader checks, then remove temporary logs, flags, fixtures, recordings, breakpoints, and instrumentation.

Complete when: the original symptom is green, the regression checks pass or their failures are reported, temporary debugging artifacts are removed, and the evidence connects the fix to the root cause.

Report

Return:

  • Root cause: causal mechanism and affected path.
  • Evidence: decisive observations and falsified alternatives.
  • Fix: changed files and why the change addresses the cause.
  • Verification: red-to-green loop and broader checks with results.
  • Remaining risk: unresolved uncertainty or unsupported environments, if any.
  • Prevention: only when a concrete preventive change follows from the evidence.
Files (skills)
  • SKILL.md 5.9 KB
    ---
    name: debug
    description: >-
      Debug errors, test failures, incorrect output, browser failures, intermittent bugs,
      and performance regressions through a tight red/green diagnosis loop. Use when
      behavior is broken, failing, flaky, slow, or unexplained.
    ---
    
    # Debug
    
    Build a **tight**, red-capable feedback loop before changing code. Then minimize,
    test falsifiable hypotheses, fix the root cause, and drive the same loop green.
    
    ## 1. Establish the symptom safely
    
    Capture the user's exact observable symptom: error, wrong output, UI state, failed
    request, or measured latency. Record the triggering input, environment, and expected
    versus actual behavior.
    
    Redact secrets before displaying or saving evidence:
    
    - Replace credentials, tokens, cookies, authorization headers, and personal data with
      `<REDACTED>`.
    - Record environment-variable names and presence by default, not values.
    - Keep credentials in the environment when building reproduction scripts.
    
    **Complete when:** the symptom and expected behavior are precise enough that the
    final verification can distinguish fixed from unfixed without relying on judgment.
    
    ## 2. Build a tight red loop
    
    Create one command or agent-runnable action sequence that exercises the user's exact
    symptom and returns an unambiguous pass/fail result. Prefer, in order, an existing
    failing test, a focused test, an HTTP or CLI script, a browser automation flow, or a
    replay of captured input.
    
    For browser-visible or interaction bugs, invoke the installed `agent-browser` skill.
    Use it to drive the reproduction and capture relevant DOM state, console or page
    errors, network evidence, screenshots, traces, or video. Keep authentication
    human-controlled or in its auth vault.
    
    Run the loop at least once and show the invocation and redacted failing signal. A
    tight loop is:
    
    - **Red-capable:** fails on the user's exact symptom, not a nearby error.
    - **Deterministic:** returns the same verdict, or a measured and pinned failure rate.
    - **Fast:** cheap enough to run after every experiment.
    - **Agent-runnable:** runs unattended whenever automation can reach the behavior.
    
    For intermittent bugs, measure a baseline failure rate and raise it through repeated
    runs, controlled timing, concurrency, load, or replayed input. Record the conditions
    and sample size so the same experiment can be repeated after the fix.
    
    If no useful loop can be built, stop and list what was tried. Request the missing
    environment access, a redacted HAR/log/trace/recording, or permission for temporary
    production instrumentation. Use a structured human-driven loop only when automation
    cannot perform an irreducibly human action such as 2FA, biometrics, or physical-device
    interaction.
    
    **Complete when:** one already-run command or action sequence is red-capable,
    repeatable, and fast enough to guide diagnosis.
    
    ## 3. Reproduce and minimize
    
    Run the loop until the failure is understood at the observable level. Shrink inputs,
    steps, config, data, and dependencies one at a time; rerun after every cut and retain
    only what keeps the loop red. For intermittent bugs, preserve the pinned conditions
    and report the measured failure rate rather than claiming determinism.
    
    **Complete when:** the smallest practical scenario still produces the exact symptom,
    and its invocation, inputs, conditions, and failure signal are recorded.
    
    ## 4. Rank falsifiable hypotheses
    
    Generate 3–5 plausible root-cause hypotheses before testing any one of them. For each,
    record:
    
    - supporting evidence;
    - contradicting or missing evidence;
    - the observation predicted if it is true;
    - the cheapest experiment that distinguishes it from the alternatives.
    
    Rank by explanatory power and test cost. Discard or sharpen any hypothesis that makes
    no falsifiable prediction.
    
    **Complete when:** the hypotheses are ranked and the next experiment has a predicted
    result that can support or reject one or more of them.
    
    ## 5. Run one-variable experiments
    
    Change one variable at a time and map every probe to a prediction from Phase 4. Use
    focused logging, a debugger, config or input substitution, dependency isolation, or
    history comparison as the hypothesis requires. Inspect recent changes, versions,
    configuration, service state, and timing only when they distinguish live hypotheses.
    
    Use `git bisect` only with a known-good revision and the red/green loop as its test;
    restore the original repository state with `git bisect reset` afterward. Keep
    instrumentation temporary and redact its output.
    
    After each experiment, record the command, result, and which hypotheses gained or
    lost support. Update the ranking before choosing the next experiment.
    
    **Complete when:** evidence identifies the causal mechanism and explains the observed
    symptom; correlation or a disappearing symptom alone is insufficient.
    
    ## 6. Prove, fix, and clean up
    
    When a stable test seam exists, add a regression test before the fix and run it red on
    the reported symptom. Otherwise, state why the reproduction loop is the appropriate
    verification artifact. Apply the smallest change that addresses the causal mechanism.
    
    Run the regression test or original loop green. For intermittent bugs, use the same
    conditions and sample size as the baseline. Run the relevant broader checks, then
    remove temporary logs, flags, fixtures, recordings, breakpoints, and instrumentation.
    
    **Complete when:** the original symptom is green, the regression checks pass or their
    failures are reported, temporary debugging artifacts are removed, and the evidence
    connects the fix to the root cause.
    
    ## Report
    
    Return:
    
    - **Root cause:** causal mechanism and affected path.
    - **Evidence:** decisive observations and falsified alternatives.
    - **Fix:** changed files and why the change addresses the cause.
    - **Verification:** red-to-green loop and broader checks with results.
    - **Remaining risk:** unresolved uncertainty or unsupported environments, if any.
    - **Prevention:** only when a concrete preventive change follows from the evidence.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.