Debugging with Evidence

Diagnose unexpected behavior with a reproduction, competing explanations and experiments that separate them before fixing. Use for bugs, failed checks or repeated unsuccessful fixes; attribute branch failures only with suitable comparison evidence.

33 stars 4 forksSoftware Development Plugin marketplace

Install

Claude Code plugin
/plugin marketplace add okgrit/done-is-a-claim

The repo is a Claude Code plugin marketplace. Run /plugin afterwards to pick the plugin that includes this skill.

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add okgrit/done-is-a-claim --skill debugging-with-evidence
Manual install
git clone --depth 1 https://github.com/okgrit/done-is-a-claim.git /tmp/done-is-a-claim
mkdir -p ~/.claude/skills
cp -r /tmp/done-is-a-claim/skills/debugging-with-evidence ~/.claude/skills/debugging-with-evidence

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# Debugging with evidence

An observed failure establishes that something happened under particular
conditions. Find the mechanism that explains it before changing another thing.
Keep the investigation tied to the user's outcome and authorized file scope.

## Capture the failure

1. Record expected and observed behavior, exact command or user action,
   revision, dirty inputs, environment, relevant order or seed and evidence path.
2. Read the complete error and inspect the affected artifact and relevant diff.
   Missing paths, absent tools, empty test collection and permission errors
   may explain an unrunnable check; they do not establish successful behavior.
3. Reproduce with the smallest scope that still preserves the failure. Retain
   the original run: narrowing can remove order, shared state or boundary effects.
4. Register cleanup before an experiment that creates temporary resources.
   Use read-only inspection to answer state questions; do not reset or destroy
   the working tree to learn what was changed.

## Test explanations

Write a small set of plausible hypotheses based on the observation. For each,
name the predicted result and the observation that would contradict it. Choose
an experiment whose outcomes separate at least two explanations. Repeating the
same failed run without changing a discriminating condition adds little evidence.

Change one relevant condition where feasible and capture the actual outcome.
Read the full skill on GitHub

Details

Skill name
debugging-with-evidence
Path
skills/debugging-with-evidence/SKILL.md
License
Apache-2.0
Repo updated
25 October 2026

FAQ

What does the Debugging with Evidence skill do?

Diagnose unexpected behavior with a reproduction, competing explanations and experiments that separate them before fixing. Use for bugs, failed checks or repeated unsuccessful fixes; attribute branch failures only with suitable comparison evidence.

How do I install the Debugging with Evidence skill?

Claude Code plugin: /plugin marketplace add okgrit/done-is-a-claim. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Debugging with Evidence popular?

It lives in okgrit/done-is-a-claim, which has 33 GitHub stars and 4 forks, and is included in 1 curated skill list.

Related skills

Acceptance Design

33

okgrit/done-is-a-claim

Define executable acceptance for a bounded task before work or dispatch. Use when writing a worker brief, selecting success checks, or repairing an acceptance contract that cannot test the intended outcome.

Testing & QAIn 1 list

Checking Delivery

33

okgrit/done-is-a-claim

Verify an artifact at its actual delivery destination and distinguish send attempts, acknowledgements, publication and consumer checks. Use when reporting a file, message, export or deployment as delivered; creating a local draft alone does not imply delivery.

DevOps & CloudIn 1 list

Collecting Worker Results

33

okgrit/done-is-a-claim

Inspect a stopped worker's returned work and evidence before accepting it, retrying it or handing it to an integration owner. Use when a worker finishes, records disagree, or a green result has no visible change. Collection does not authorize merging.

OtherIn 1 list

Nist Csf

33

scytale-labs/GRC-Claude-Skills

Use when the user asks about NIST Cybersecurity Framework — the CSF 2.0 six Functions (Govern, Identify, Protect, Detect, Respond, Recover), Categories and Subcategories, Implementation Tiers (1–4), Profiles (Current and Target), Organizational Profile, or using CSF as a structuring lens for a security program. Voluntary framework — useful for any sector, often paired with sector-specific regulation.

Software Development14

Debug Replay

48

amplitude/mcp-marketplace

Turns bug reports into reproducible steps by finding error sessions in Amplitude Session Replay, extracting interaction timelines, and identifying the common action sequence that precedes the failure. Use when a user reports a bug, an error event spikes, someone says "how do I reproduce this", "what happened to user X", "repro steps", or you need to understand what a user did before an error occurred.

Software Development12

Squad Conventions

45

Azure-Samples/agent-skills-dotnet-demo

Core conventions and patterns used in the Squad codebase

Software Development11

Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.