Skip to content
Skills Library
Programming · Analysis

evanflow-debug

/evanflow-debug

Root-cause discipline for bugs, test failures, and unexpected behavior. Embedded grill on the hypothesis before writing fix code. Use when encountering any bug, failing test, or behavior that doesn't match expectation.

Repository
evanflow ↗
Licence
MIT
Last repository change
12.05.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
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 12.05.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

Root-cause discipline for bugs, test failures, and unexpected behavior. Embedded grill on the hypothesis before writing fix code. Use when encountering any bug, failing test, or behavior that doesn't match expectation.

Original author description

Root-cause discipline for bugs, test failures, and unexpected behavior. Embedded grill on the hypothesis before writing fix code. Use when encountering any bug, failing test, or behavior that doesn't match expectation.

How it works

  1. Vocabulary
  2. When to Use
  3. The Flow
  4. Hard Rules
  5. Hand-offs
Original SKILL.md headings · 72 lines, 457 words
SKILL.md preview
---
name: evanflow-debug
description: Root-cause discipline for bugs, test failures, and unexpected behavior. Embedded grill on the hypothesis before writing fix code. Use when encountering any bug, failing test, or behavior that doesn't match expectation.
---

# EvanFlow: Debug


## Vocabulary

See `evanflow` meta-skill.

## When to Use

- Test failing
- User reports unexpected behavior
- Production error
- Code does the wrong thing under specific conditions
- Anything where the immediate symptom isn't the root cause

**SKIP when:** the cause is obvious and the fix is one line. Don't ceremonialize trivial bugs.

## The Flow

### 1. Reproduce

- Get the exact reproduction: input, environment, steps
- Reproduce locally if possible. If you can't reproduce, the bug is unverified — say so before proceeding.

### 2. Form a Hypothesis

State the hypothesis explicitly:

> "I think the bug is in <file>:<line> because when X happens, Y is supposed to happen but instead Z does."

A vague "probably the validation" is not a hypothesis.

### 3. Embedded Grill — Challenge the Hypothesis

Before writing any fix, ask:

- **Symptom vs. cause**: "Is this where the bug *manifests*, or where it *originates*? Trace one step further upstream."
- **Coverage**: "What other code paths share this root cause? Will the fix here leave those paths broken?"
- **Reversibility**: "Does the fix have the same blast radius as the bug, or wider?"
- **Test gap**: "Why didn't a test catch this? Is the test missing, wrong, or misaligned with real behavior?"
- **Domain check**: "Is the bug actually behaving correctly per spec, and the spec is wrong?"

### 4. Verify the Hypothesis Before Fixing

Add an instrument (log, breakpoint, test assertion) that proves the hypothesis right or wrong. **Watch the instrument fire.** If it doesn't, the hypothesis is wrong — go back to step 2.

### 5. Write a Failing Test First

The test should fail because the bug exists. This is a vertical-slice TDD application — see `evanflow-tdd`.

### 6. Fix at the Root

Fix where the root cause originates, not where the symptom appears. If the fix is far from the symptom, leave a comment explaining the WHY (this is one of the few cases where a code comment earns its keep).

### 7. Verify the Test Passes

Run the test. Run the broader suite. Confirm no regressions.

## Hard Rules

- **No fix without a failing test that demonstrates the bug.** (Same TDD principle as evanflow-tdd.)
- **Fix the root, not the symptom.** Symptom-fixes are how bugs metastasize.
- **Never auto-commit.** A fix gets staged; user confirms before commit.
- **If you can't reproduce, say so.** Don't fix invisible bugs.

## Hand-offs

- Fix complete, tests pass → if mid-plan, return to `evanflow-executing-plans`. If standalone debug, **report what was fixed and STOP**. The user decides whether to commit or take further action.
- Discovered an architectural issue → `evanflow-improve-architecture`
- Discovered the spec is wrong → `evanflow-brainstorming` to align on intended behavior

Versions

The database has no other skills named evanflow-debug.

Database snapshot: 13.11.2026 · package version 1601358139a4 (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

  • 100root-cause-debugging
    Debug by finding the root cause before changing code: reproduce, read the full error, check what changed, form one hypothesis at a time and test it, write the failing test, then fix; with a hard stop after three failed fixes to question the approach. Use when a test fails, a bug…
  • 90debug
    Use when encountering any bug, test failure, or unexpected behavior. Requires root cause investigation before proposing fixes. No guessing.
  • 100debug-root-cause
    Systematically find and fix the root cause of bugs, errors, failing tests, and crashes in JavaScript/TypeScript and Python. Use whenever the user pastes an error or stack trace, says something is broken, "not working", "error", "kenapa gagal", "bug", a test fails, or behavior is…
  • 90investigate
    Systematic debugging skill. Use when encountering a bug, test failure, unexpected behavior, or when asked to "investigate", "debug", "diagnose", or "figure out why". Enforces root-cause-first discipline with structured hypothesis tracking.
  • 100systematic-debugging
    Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
  • 100systematic-debugging
    Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

Feedback and reports

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