debug

Name: debug
Author: softspark

161stars21forks

How to install debug?

softspark/ai-toolkit/debug

$npx -y skills add softspark/ai-toolkit --skill debug

Installs into the current project.

Summary

Systematic debugging via logs, health checks, hypothesis-driven investigation. Triggers: debug, error, trace root cause, fix bug, reproduce symptom, investigation.

Files · 1

View on GitHub

SKILL.md

1	# Debug Helper
2
3	$ARGUMENTS
4
5	Systematic debugging for application issues.
6
7	## Project context
8
9	- Recent logs: !`docker compose logs --tail 20 2>/dev/null \|\| tail -20 logs/*.log 2>/dev/null \|\| echo "no-logs-found"`
10
11	## Automated Error Parsing
12
13	Pipe error output through the error parser for structured diagnosis:
14
15	```bash
16	# Pipe from failing command
17	your_command 2>&1 \| python3 "$(dirname "$0")/scripts/error-parser.py"
18
19	# Or from a log file
20	cat /var/log/app/error.log \| python3 scripts/error-parser.py
21	```
22
23	The script outputs JSON with:
24	- language: detected language (python/node/go/php)
25	- error_type: extracted error class (e.g., ModuleNotFoundError)
26	- message: the error message text
27	- category: classification (import, reference, type, connection, timeout, memory, permission, syntax)
28	- stack_frames: parsed file/line/function from the stack trace
29	- files_to_check: unique files from the trace, ordered by relevance
30	- common_causes: likely root causes for this error category
31
32	Use the parsed output to focus investigation on the right files and hypotheses.
33
34	---
35
36	## Methodology — The Iron Law
37
38	```
39	NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
40	```
41
42	Random fixes waste time and create new bugs. Quick patches mask underlying issues. Complete each phase before proceeding to the next.
43
44	### Phase 1 — Root Cause Investigation
45	Read error messages and stack traces completely. Reproduce reliably (or gather more data — don't guess). Check recent changes (`git diff`, new deps, config). For multi-component systems: log boundary in/out at each layer, identify WHERE it breaks before WHY.
46
47	### Phase 2 — Pattern Analysis
48	Find similar working code in the same codebase. Compare against references completely, not skimming. List every difference, however small.
49
50	### Phase 3 — Hypothesis & Testing
51	Form a single hypothesis ("X is the root cause because Y"). Test minimally — smallest possible change, one variable at a time. Verify before continuing — if it didn't work, form a NEW hypothesis. Don't stack fixes on top of fixes.
52
53	### Phase 4 — Implementation
54	Write a failing test case FIRST (use `/tdd`). Implement single fix at root cause. No "while I'm here" improvements.
55
56	### "5 Whys" — depth gate
57	Ask "Why?" at least 5 times to find the real issue. Stop at the first plausible answer = symptom fixing. Example: crash → null pointer → user object null → API 404 → invalid user ID → frontend allowed negative IDs (root cause).
58
59	### Architecture escalation (3+ failed fixes)
60	If three hypotheses failed and each fix reveals new shared state in different places, the architecture is wrong, not your hypothesis. STOP. Discuss with user before more attempts.
61
62	---
63
64	## Debugging Workflow
65
66	### 1. Check Logs
67
68	```bash
69	# Application logs (auto-detect environment)
70	# Docker:
71	docker compose logs --tail 100 {service} 2>&1 \| grep -i error
72
73	# Bare metal / systemd:
74	journalctl -u {service} --since "1 hour ago" \| grep -i error
75
76	# Log files:
77	tail -100 logs/app.log \| grep -i error
78	```
79
80	### 2. Check Service Health
81
82	```bash
83	# Docker environment
84	docker compose ps
85
86	# Process check
87	ps aux \| grep -E "(node\|python\|java\|php)" \| grep -v grep
88
89	# HTTP health endpoints
90	curl -sf http://localhost:{port}/health
91	```
92
93	### 3. Interactive Debug
94
95	```bash
96	# Python
97	python3 -c "import module; print(module.function('test'))"
98
99	# Node.js
100	node -e "const m = require('./module'); console.log(m.fn('test'))"
101
102	# PHP
103	php -r "require 'vendor/autoload.php'; echo MyClass::method('test');"
104	```
105
106	### 4. Database Checks
107
108	```bash
109	# PostgreSQL
110	psql -U postgres -c "SELECT version();"
111
112	# MySQL
113	mysql -e "SELECT VERSION();"
114
115	# Redis
116	redis-cli ping && redis-cli info memory
117
118	# MongoDB
119	mongosh --eval "db.runCommand({ping:1})"
120	```
121
122	## Common Debug Scenarios
123
124	### API Returns 500
125	```bash
126	# Check server logs for stack traces
127	grep -A5 "Traceback\\|Error\\|Exception" logs/app.log
128	```
129
130	### Slow Performance
131	```bash
132	# Resource usage
133	top -bn1 \| head -20 # CPU/memory
134	iostat -x 1 3 # Disk I/O
135	ss -tlnp # Open connections
136	```
137
138	### Connection Issues
139	```bash
140	# Test connectivity
141	curl -I http://localhost:{port}
142	nc -zv {host} {port}
143	```
144
145	## Parallel Hypothesis Debugging (Agent Teams)
146
147	For complex bugs (open >1h, unclear root cause), spawn teammates to investigate competing hypotheses:
148
149	```
150	Create an agent team to debug this issue:
151	- Teammate 1 (debugger): "Investigate if [bug] is caused by [hypothesis A: database issue].
152	Check logs, connection pools, timeouts, query performance."
153	Use Opus.
154	- Teammate 2 (debugger): "Investigate if [bug] is caused by [hypothesis B: race condition].
155	Look for async issues, locking, concurrency, shared state."
156	Use Opus.
157	- Tea

People who liked this also viewed

6 picks

Type

azure-diagnosticsDebug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deploySkillsJul 2026472k1.3k
systematic-debuggingUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesSkillsJul 2026197k259k
safe-debugRigor Debug / Rigor Audit skill for deep learning research work. Use when the user pastes a traceback, terminal error, CUDA OOM, checkpoint load failure, shape mismatch, NaN loss symptom, or training SkillsMay 2026161k507
explore-runRigor Improve / Rigor Explore run leaf skill for bounded exploratory evidence in deep learning research repositories. Use when the researcher explicitly authorizes exploratory runs such as small-subseSkillsMay 2026161k507
minimal-run-and-auditRigor Run skill for README-first deep learning repo reproduction. Use when the task is specifically to capture or normalize evidence from the selected smoke test or documented inference or evaluation SkillsMay 2026161k507
insforge-debugUse when diagnosing problems in an InsForge project — reactive failures (SDK error object, HTTP 4xx/5xx, gateway timeout 502/503/504, edge function failure or timeout, login/OAuth/auth errors, RLS denSkillsJul 202618k31

debug

161stars21forks

View on GitHub

How to install debug?

softspark/ai-toolkit/debug

$npx -y skills add softspark/ai-toolkit --skill debug

Installs into the current project.

Summary

Systematic debugging via logs, health checks, hypothesis-driven investigation. Triggers: debug, error, trace root cause, fix bug, reproduce symptom, investigation.

Files · 1

View on GitHub

SKILL.md

1	# Debug Helper
2
3	$ARGUMENTS
4
5	Systematic debugging for application issues.
6
7	## Project context
8
9	- Recent logs: !`docker compose logs --tail 20 2>/dev/null \|\| tail -20 logs/*.log 2>/dev/null \|\| echo "no-logs-found"`
10
11	## Automated Error Parsing
12
13	Pipe error output through the error parser for structured diagnosis:
14
15	```bash
16	# Pipe from failing command
17	your_command 2>&1 \| python3 "$(dirname "$0")/scripts/error-parser.py"
18
19	# Or from a log file
20	cat /var/log/app/error.log \| python3 scripts/error-parser.py
21	```
22
23	The script outputs JSON with:
24	- language: detected language (python/node/go/php)
25	- error_type: extracted error class (e.g., ModuleNotFoundError)
26	- message: the error message text
27	- category: classification (import, reference, type, connection, timeout, memory, permission, syntax)
28	- stack_frames: parsed file/line/function from the stack trace
29	- files_to_check: unique files from the trace, ordered by relevance
30	- common_causes: likely root causes for this error category
31
32	Use the parsed output to focus investigation on the right files and hypotheses.
33
34	---
35
36	## Methodology — The Iron Law
37
38	```
39	NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
40	```
41
42	Random fixes waste time and create new bugs. Quick patches mask underlying issues. Complete each phase before proceeding to the next.
43
44	### Phase 1 — Root Cause Investigation
45	Read error messages and stack traces completely. Reproduce reliably (or gather more data — don't guess). Check recent changes (`git diff`, new deps, config). For multi-component systems: log boundary in/out at each layer, identify WHERE it breaks before WHY.
46
47	### Phase 2 — Pattern Analysis
48	Find similar working code in the same codebase. Compare against references completely, not skimming. List every difference, however small.
49
50	### Phase 3 — Hypothesis & Testing
51	Form a single hypothesis ("X is the root cause because Y"). Test minimally — smallest possible change, one variable at a time. Verify before continuing — if it didn't work, form a NEW hypothesis. Don't stack fixes on top of fixes.
52
53	### Phase 4 — Implementation
54	Write a failing test case FIRST (use `/tdd`). Implement single fix at root cause. No "while I'm here" improvements.
55
56	### "5 Whys" — depth gate
57	Ask "Why?" at least 5 times to find the real issue. Stop at the first plausible answer = symptom fixing. Example: crash → null pointer → user object null → API 404 → invalid user ID → frontend allowed negative IDs (root cause).
58
59	### Architecture escalation (3+ failed fixes)
60	If three hypotheses failed and each fix reveals new shared state in different places, the architecture is wrong, not your hypothesis. STOP. Discuss with user before more attempts.
61
62	---
63
64	## Debugging Workflow
65
66	### 1. Check Logs
67
68	```bash
69	# Application logs (auto-detect environment)
70	# Docker:
71	docker compose logs --tail 100 {service} 2>&1 \| grep -i error
72
73	# Bare metal / systemd:
74	journalctl -u {service} --since "1 hour ago" \| grep -i error
75
76	# Log files:
77	tail -100 logs/app.log \| grep -i error
78	```
79
80	### 2. Check Service Health
81
82	```bash
83	# Docker environment
84	docker compose ps
85
86	# Process check
87	ps aux \| grep -E "(node\|python\|java\|php)" \| grep -v grep
88
89	# HTTP health endpoints
90	curl -sf http://localhost:{port}/health
91	```
92
93	### 3. Interactive Debug
94
95	```bash
96	# Python
97	python3 -c "import module; print(module.function('test'))"
98
99	# Node.js
100	node -e "const m = require('./module'); console.log(m.fn('test'))"
101
102	# PHP
103	php -r "require 'vendor/autoload.php'; echo MyClass::method('test');"
104	```
105
106	### 4. Database Checks
107
108	```bash
109	# PostgreSQL
110	psql -U postgres -c "SELECT version();"
111
112	# MySQL
113	mysql -e "SELECT VERSION();"
114
115	# Redis
116	redis-cli ping && redis-cli info memory
117
118	# MongoDB
119	mongosh --eval "db.runCommand({ping:1})"
120	```
121
122	## Common Debug Scenarios
123
124	### API Returns 500
125	```bash
126	# Check server logs for stack traces
127	grep -A5 "Traceback\\|Error\\|Exception" logs/app.log
128	```
129
130	### Slow Performance
131	```bash
132	# Resource usage
133	top -bn1 \| head -20 # CPU/memory
134	iostat -x 1 3 # Disk I/O
135	ss -tlnp # Open connections
136	```
137
138	### Connection Issues
139	```bash
140	# Test connectivity
141	curl -I http://localhost:{port}
142	nc -zv {host} {port}
143	```
144
145	## Parallel Hypothesis Debugging (Agent Teams)
146
147	For complex bugs (open >1h, unclear root cause), spawn teammates to investigate competing hypotheses:
148
149	```
150	Create an agent team to debug this issue:
151	- Teammate 1 (debugger): "Investigate if [bug] is caused by [hypothesis A: database issue].
152	Check logs, connection pools, timeouts, query performance."
153	Use Opus.
154	- Teammate 2 (debugger): "Investigate if [bug] is caused by [hypothesis B: race condition].
155	Look for async issues, locking, concurrency, shared state."
156	Use Opus.
157	- Tea

People who liked this also viewed

6 picks

Type