Skip to content
Skills Library
Programming · Analysis

debug

/debug

Debug errors and unexpected behavior with log analysis. Use for issues and error messages.

Repository
dotfiles ↗
Licence
MIT
Last repository change
10.10.2026

Assessment and security

100/ 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.
Content35 / 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 10.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

Debug errors and unexpected behavior with log analysis. Use for issues and error messages.

Original author description

Debug errors and unexpected behavior with log analysis. Use for issues and error messages.

How it works

  1. Usage
  2. Options
  3. When to Use
  4. Debugging Process
  5. Investigation Steps
  6. Log Analysis (--logs)
  7. Correlation Queries (--correlate)
  8. Stack Trace Analysis (--trace)
  9. Investigation Checklist
  10. Output Format
Original SKILL.md headings · 177 lines, 690 words
SKILL.md preview
---
name: debug
description: Debug errors and unexpected behavior with log analysis. Use for issues and error messages.
---

# Debug

Systematic debugging for errors, test failures, unexpected behavior, and production issues.

## Usage

```
/debug [issue] [--logs] [--correlate] [--trace] [--type bug|build|perf|deploy]
```

## Options

| Flag          | Purpose                                                      |
| ------------- | ------------------------------------------------------------ |
| `--logs`      | Enable log pattern analysis (error spikes, frequency, types) |
| `--correlate` | Run SQL correlation queries on structured logs               |
| `--trace`     | Deep stack trace analysis with context                       |
| `--type`      | Issue category: bug, build, perf(ormance), deploy(ment)      |

## When to Use

- Error messages or stack traces appear
- Tests are failing
- Code behaves unexpectedly
- User says "it's broken" or "not working"
- Production errors need investigation (`--logs`)
- Need to correlate errors across systems (`--correlate`)
- Deep stack analysis required (`--trace`)

## Debugging Process

1. **Capture** - Get error message, stack trace, and reproduction steps
2. **Isolate** - Narrow down the failure location
3. **Hypothesize** - Form theories about the cause
4. **Test** - Validate hypotheses with evidence
5. **Fix** - Implement minimal fix
6. **Verify** - Confirm solution works

## Investigation Steps

```bash
# Check recent changes that might have caused the issue
git log --oneline -10
git diff HEAD~3

# Find error patterns in logs
grep -r "error\|Error\|ERROR" logs/ 2>/dev/null | tail -20

# Check test output
npm test 2>&1 | tail -50  # or pytest, cargo test, etc.
```

## Log Analysis (`--logs`)

### Find Errors

```bash
# Recent errors with context
grep -B 5 -A 10 "ERROR" /var/log/app.log

# Count by error type
grep -oE "Error: [^:]*" app.log | sort | uniq -c | sort -rn

# Errors in time range
awk '/2024-01-15 14:/ && /ERROR/' app.log

# Find repeated errors
grep "ERROR" app.log | cut -d']' -f2 | sort | uniq -c | sort -rn | head -20

# Find error spikes
grep "ERROR" app.log | cut -d' ' -f1-2 | uniq -c | sort -rn
```

### Common Patterns

| Pattern            | Indicates          | Action                   |
| ------------------ | ------------------ | ------------------------ |
| NullPointer        | Missing null check | Add validation           |
| Timeout            | Slow dependency    | Add timeout, retry       |
| Connection refused | Service down       | Check health, retry      |
| OOM                | Memory leak        | Profile, increase limits |
| Rate limit         | Too many requests  | Add backoff, queue       |

## Correlation Queries (`--correlate`)

```sql
-- Errors by endpoint
SELECT endpoint, count(*) as errors
FROM logs
WHERE level = 'ERROR' AND time > NOW() - INTERVAL '1 hour'
GROUP BY endpoint ORDER BY errors DESC;

-- Error rate over time
SELECT
  date_trunc('minute', time) as minute,
  count(*) filter (where level = 'ERROR') as errors,
  count(*) as total
FROM logs
WHERE time > NOW() - INTERVAL '1 hour'
GROUP BY minute ORDER BY minute;

-- Correlate request IDs across services
SELECT service, message, time
FROM logs
WHERE request_id = 'req-12345'
ORDER BY time;
```

## Stack Trace Analysis (`--trace`)

### Parse Stack Traces

```python
import re

def parse_stack_trace(log_content: str) -> list[dict]:
    pattern = r'(?P<exception>\w+Error|\w+Exception): (?P<message>.*?)\n(?P<trace>(?:\s+at .+\n)+)'
    traces = []
    for match in re.finditer(pattern, log_content):
        traces.append({
            'type': match.group('exception'),
            'message': match.group('message'),
            'trace': match.group('trace').strip().split('\n')
        })
    return traces
```

## Investigation Checklist

1. **Capture** - Get full error message and stack trace
2. **Timestamp** - When did it start?
3. **Frequency** - How often? Increasing?
4. **Scope** - All users or specific?
5. **Changes** - Recent deployments?
6. **Dependencies** - External services affected?

## Output Format

```markdown
## Debug Report

**Issue:** [Brief description]
**Root Cause:** [What's actually wrong]

### Evidence

- [Finding 1]
- [Finding 2]

### Fix

[Code or configuration change]

### Verification

[How to confirm the fix works]

### Prevention

[How to prevent this in the future]
```

## Examples

**Input:** "TypeError: Cannot read property 'map' of undefined"
**Action:** Trace the undefined value, find where data should be initialized, fix the source

**Input:** "Tests are failing"
**Action:** Run tests, capture failures, analyze each failure, fix underlying issues

**Input:** `/debug --logs "API returning 500 errors"`
**Action:** Search logs for 500 status, find stack traces, identify root cause, check error frequency

**Input:** `/debug --correlate "intermittent failures"`
**Action:** Run correlation queries to find patterns, identify affected endpoints, correlate with events

Versions

RepositoryScoreLicence
This page · htlin222/dotfiles100MIT
ericrisco/rsc-harness100MIT
nicsuzor/academicops100MIT
duronext/jig100MIT
drosam/agents100MIT
rizukirr/vibekit100MIT
DingyangLyu/MatClaw100Apache-2.0
Kanevry/session-orchestrator100MIT
kdlbs/kandev100AGPL-3.0

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

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

  • 90vc:debug
    Debug systematically with root-cause analysis before fixes. Use for bugs, test failures, unexpected behavior, performance issues, CI failures, or system investigation.
  • 90vc:debug
    Debug systematically with root-cause analysis before fixes. Use for bugs, test failures, unexpected behavior, performance issues, CI failures, or system investigation.
  • 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.
  • 100debugging
    Systematically debug code issues using proven methodologies. Use when encountering errors, unexpected behavior, or performance problems. Handles error analysis, root cause identification, debugging strategies, and fix verification.
  • 100debug-deep
    Deep debugging using multi-agent analysis and error pattern matching. Use when user reports a bug, error, crash, or unexpected behavior. Triggers on "debug", "fix", "broken", "crash", "error", "bug".
  • 100craftsman-debug
    Systematic debugging using ReAct pattern. Use when encountering bugs, errors, unexpected behavior, test failures, or performance issues. Never guess - investigate methodically.

Feedback and reports

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