Skip to content
Skills Library
Programming · Analysis

debug-sop

/debug-sop

Diagnose errors, failed tests, crashes, hangs, regressions, suspicious outputs, and unexpected experimental results through reproducible hypothesis-driven debugging. Use whenever a script or system behaves incorrectly, even if the user only says it is broken or pastes an error. Respect diagnosis-only requests; implement a fix only when authorized.

Repository
aiscientist ↗
Licence
MIT
Last repository change
09.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 09.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Diagnose errors, failed tests, crashes, hangs, regressions, suspicious outputs, and unexpected experimental results through reproducible hypothesis-driven debugging. Use whenever a script or system behaves incorrectly, even if the user only says it is broken or pastes an error. Respect diagnosis-only requests; implement a fix only when authorized.

Original author description

Diagnose errors, failed tests, crashes, hangs, regressions, suspicious outputs, and unexpected experimental results through reproducible hypothesis-driven debugging. Use whenever a script or system behaves incorrectly, even if the user only says it is broken or pastes an error. Respect diagnosis-only requests; implement a fix only when authorized.

How it works

  1. Inputs and output
  2. 1. Recover history before guessing
  3. 2. Reproduce and bound the failure
  4. 3. Build and eliminate hypotheses
  5. 4. Isolate the root cause
  6. 5. Fix only when authorized
  7. 6. Verify proportionally
  8. 7. Record the failure
  9. Recovery branches
  10. Completion criteria
Original SKILL.md headings · 104 lines, 616 words
SKILL.md preview
---
name: debug-sop
description: Diagnose errors, failed tests, crashes, hangs, regressions, suspicious outputs, and unexpected experimental results through reproducible hypothesis-driven debugging. Use whenever a script or system behaves incorrectly, even if the user only says it is broken or pastes an error. Respect diagnosis-only requests; implement a fix only when authorized.
---

# Debug SOP

## Inputs and output

Capture the exact symptom, expected behavior, reproduction command, relevant
inputs, environment, first known bad state, and whether fixing is authorized.
Return a compact incident report with reproduction, root cause or surviving
hypotheses, evidence, changed files if any, verification commands, and the
failure-ledger id.

## 1. Recover history before guessing

1. Call `mcp__memory__match_signatures` with the exact error plus the operation
   that triggered it. Read matching resolutions, but verify they still apply.
2. Inspect recent relevant changes, logs, configuration, and run manifests.
3. Distinguish the visible symptom from a proposed cause. Do not edit merely
   because a familiar exception suggests an easy fix.

## 2. Reproduce and bound the failure

1. Run the smallest safe command that should reproduce the symptom.
2. Record whether it is deterministic, intermittent, machine-specific,
   data-specific, or dependent on ordering/timing.
3. If reproduction would be destructive, costly, or use reserved data, stop
   and request the needed authority or choose a non-mutating probe.
4. If the failure cannot be reproduced, compare environment, command, inputs,
   Git state, and dependency locks before declaring it gone.

## 3. Build and eliminate hypotheses

List plausible causes and, for each, the cheapest observation that would
distinguish it. Prefer direct evidence in this order:

1. exact traceback, exit code, or incorrect output;
2. minimal reproduction;
3. focused logging or state inspection;
4. controlled input/config variation;
5. history or non-destructive bisection.

Change one explanatory variable at a time. Do not use destructive Git reset or
discard unrelated user work during bisection.

## 4. Isolate the root cause

Reduce the case until removing one condition removes the failure. For data or
statistical failures, also check leakage, seed sensitivity, stale code/config,
and baseline-budget mismatch. For integration failures, verify each boundary
separately: executable discovery, configuration loading, process startup,
protocol exchange, shared workspace/state path, then UI behavior.

If multiple causes remain possible, say which evidence is missing instead of
choosing the most convenient story.

## 5. Fix only when authorized

For a diagnosis request, stop after proving the cause and proposing a scoped
fix. For a requested repair:

1. make the smallest change that removes the cause;
2. preserve compatibility and unrelated user changes;
3. add or update a regression test that failed before the fix;
4. avoid hiding the symptom with broad exception handling or relaxed checks.

## 6. Verify proportionally

Run the minimal reproduction first, then the focused regression tests, then
the repository-required broader checks. Verify the original user-visible path,
not only the helper function. For intermittent failures, repeat enough times to
make the remaining uncertainty explicit.

## 7. Record the failure

Call `mcp__memory__record_failure` with:

- `trigger`: operation and preconditions;
- `symptom`: exact externally visible failure;
- `root_cause`: proven mechanism, not a guess;
- `resolution`: change and verification command;
- appropriate empirical or proof domain.

If unresolved, record the diagnostic evidence and surviving hypotheses rather
than inventing a root cause.

## Recovery branches

- Cannot reproduce: compare manifests and ask for the missing command/input.
- Flaky: identify timing, ordering, shared-state, or randomness dimensions and
  run controlled repetitions.
- External dependency failure: prove the local boundary is healthy, record the
  upstream error, and provide a safe retry or fallback.
- Fix causes a different regression: revert only your scoped change, preserve
  evidence, and return to the hypothesis list.
- Repeated dead end: stop changing code, summarize tested hypotheses, and state
  the exact user input or external change needed.

## Completion criteria

Debugging is complete when the symptom is reproducible or its absence is
explained, the root cause is supported by discriminating evidence, any
authorized fix passes the original reproduction and regression checks, and the
failure ledger contains enough detail for the next agent to avoid repeating
the investigation.
Files in this package (2)
  • SKILL.md 5 KB
  • evals/evals.json 2 KB

Versions

The database has no other skills named debug-sop.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 3ce64fbc8a27 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90debug
    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.
  • 86vibe-debug
    Diagnose and fix a reproducible failure in an existing project. Use for crashes, broken behavior, or failing checks, not greenfield planning.
  • 85bug-diagnosis
    Diagnose broken behavior, errors, hangs, intermittent failures, or regressions with a measured reproduction loop, ranked hypotheses, root-cause proof, regression tests, and cleanup. Includes incident recovery and runtime or trace forensics. Use when something "is broken",…
  • 100debug-error
    Diagnose one bug with hypotheses and runtime evidence before fixing. Use when "debug this error" or behavior is unexpected. FE↔BE mismatch → debug-fe-be-integration. Bug to PR → workflow-fix-and-ship. Sentry backlog → debug-sentry-monitor.
  • 100debug
    Debug errors and unexpected behavior with log analysis. Use for issues and error messages.
  • 100debug
    Systematic debugging with hypothesis-driven investigation. Use when something is broken, tests are failing, unexpected behavior occurs, or errors need investigation. Triggers on: 'this is broken', 'debug', 'why is this failing', 'unexpected error', 'not working', 'bug', 'fix…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.