debug

Name: debug
Author: jgamaraalv

8installs0forks

How to install debug?

jgamaraalv/ts-dev-kit/debug

$npx -y skills add jgamaraalv/ts-dev-kit --skill debug

Installs into the current project.

Summary

End-to-end debugging workflow that triages, reproduces, and fixes bugs across the full stack using multi-agent orchestration. Use when: (1) encountering runtime errors in the API or web app, (2) investigating failed requests or broken user flows, (3) debugging production issues v

Files · 1

View on GitHub

SKILL.md

1	<live_context>
2	Recent git changes (regression candidates):
3	!`git log --oneline -10 2>/dev/null \|\| echo "(not a git repo)"`
4
5	Working tree status:
6	!`git status --short 2>/dev/null \|\| echo "(not a git repo)"`
7	</live_context>
8
9	<trigger_examples>
10	- "Debug why the form submission fails with a 500 error"
11	- "The dashboard page shows a blank screen after login"
12	- "API returns 403 but the user should be authorized"
13	- "Investigate this Sentry issue: PROJECT-123"
14	- "The form submits but nothing appears in the list"
15	- "Debug the notification queue — jobs are stuck"
16	</trigger_examples>
17
18	<task>
19	$ARGUMENTS
20	</task>
21
22	<workflow>
23	Follow each phase in order. Each one feeds the next.
24
25	<phase_1_triage>
26	Classify the bug before investigating. This determines which agents to dispatch.
27
28	1. Read the error description, stack trace, or reproduction steps provided by the user.
29	2. Determine the affected layers:
30
31	\| Layer \| Signals \|
32	\|-------\|---------\|
33	\| Frontend \| UI doesn't render, hydration errors, blank pages, console errors, wrong data displayed \|
34	\| API \| HTTP error codes (4xx/5xx), validation failures, timeout, wrong response body \|
35	\| Database \| Missing data, wrong query results, migration issues, connection errors \|
36	\| Queue/Worker \| Jobs stuck, not processing, duplicate execution, Redis connectivity \|
37	\| Infrastructure \| Docker containers down, ports in use, env vars missing \|
38	\| Cross-cutting \| Data flows correctly in one layer but breaks in another \|
39
40	3. Check for quick context — run these in parallel:
41
42	```bash
43	# Recent changes that might have introduced the bug
44	git log --oneline -10
45	git diff HEAD~3 --stat
46
47	# Infrastructure health
48	docker compose ps
49	```
50
51	4. If the user provided a Sentry issue URL or error ID, query Sentry for the full stack trace and event details.
52	5. If the user mentions production errors, check PostHog error tracking for frequency and user impact.
53
54	State the triage result to the user:
55
56	> TRIAGE: [layer(s)] — Brief description of what appears to be happening.
57	</phase_1_triage>
58
59	<phase_2_execution_mode>
60	Based on the triage, decide the execution mode:
61
62	SINGLE-LAYER — The bug is isolated to one layer. Debug directly without dispatching agents.
63
64	MULTI-LAYER — The bug spans 2+ layers. Act as orchestrator and dispatch specialized debugging agents.
65
66	State the decision:
67
68	> EXECUTION MODE: SINGLE-LAYER — I will investigate and fix this directly.
69
70	OR
71
72	> EXECUTION MODE: MULTI-LAYER — I will dispatch specialized agents to investigate each layer in parallel.
73	</phase_2_execution_mode>
74
75	<phase_3_reproduce>
76	Reproduce the bug before investigating. Never fix what you can't reproduce.
77
78	<reproduction_strategies>
79
80	API bugs — Use curl or Bash to hit the endpoint directly:
81	```bash
82	# Discover the API base URL and endpoints from CLAUDE.md, package.json, or route files
83	curl -v http://localhost:<port>/<endpoint> \| jq .
84	```
85
86	Frontend bugs — Use browser automation MCPs:
87	1. Call `mcp__chrome-devtools__list_pages` or `mcp__plugin_playwright_playwright__browser_tabs` to check current state.
88	2. Navigate to the affected page and take a screenshot.
89	3. Check the browser console for errors.
90	4. Inspect network requests for failed API calls.
91
92	Queue/Worker bugs — Check Redis and BullMQ state:
93	```bash
94	# Check Redis connectivity
95	redis-cli ping
96
97	# Check queue state — discover the dev command from package.json scripts
98	# e.g., yarn dev, npm run dev, or the relevant workspace command
99	```
100
101	Database bugs — Query directly:
102	```bash
103	# Discover database credentials and container names from docker-compose.yml or .env
104	docker compose exec <db-container> psql -U <user> -c "SELECT * FROM ... LIMIT 5"
105	```
106
107	If reproduction fails, add strategic logging and retry. See references/debug-dispatch.md for logging patterns.
108	</reproduction_strategies>
109	</phase_3_reproduce>
110
111	<phase_4_investigate>
112	With the bug reproduced, investigate the root cause.
113
114	<single_layer_investigation>
115	Follow the data flow from the error point backward:
116
117	1. Read the source code at the error location.
118	2. Trace inputs — where does the data come from? What transformations happen?
119	3. Form a hypothesis about the root cause.
120	4. Test the hypothesis — add logging, inspect state, check the database.
121	5. If the hypothesis is wrong, form a new one based on what you learned.
122
123	Load relevant skills before diving in:
124	- Load skills matching the technologies used in the project (discover from package.json).
125	- Common examples: backend framewor

People who liked this also viewed

6 picks

Type

debug

8installs0forks

View on GitHub

How to install debug?

jgamaraalv/ts-dev-kit/debug

$npx -y skills add jgamaraalv/ts-dev-kit --skill debug

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	<live_context>
2	Recent git changes (regression candidates):
3	!`git log --oneline -10 2>/dev/null \|\| echo "(not a git repo)"`
4
5	Working tree status:
6	!`git status --short 2>/dev/null \|\| echo "(not a git repo)"`
7	</live_context>
8
9	<trigger_examples>
10	- "Debug why the form submission fails with a 500 error"
11	- "The dashboard page shows a blank screen after login"
12	- "API returns 403 but the user should be authorized"
13	- "Investigate this Sentry issue: PROJECT-123"
14	- "The form submits but nothing appears in the list"
15	- "Debug the notification queue — jobs are stuck"
16	</trigger_examples>
17
18	<task>
19	$ARGUMENTS
20	</task>
21
22	<workflow>
23	Follow each phase in order. Each one feeds the next.
24
25	<phase_1_triage>
26	Classify the bug before investigating. This determines which agents to dispatch.
27
28	1. Read the error description, stack trace, or reproduction steps provided by the user.
29	2. Determine the affected layers:
30
31	\| Layer \| Signals \|
32	\|-------\|---------\|
33	\| Frontend \| UI doesn't render, hydration errors, blank pages, console errors, wrong data displayed \|
34	\| API \| HTTP error codes (4xx/5xx), validation failures, timeout, wrong response body \|
35	\| Database \| Missing data, wrong query results, migration issues, connection errors \|
36	\| Queue/Worker \| Jobs stuck, not processing, duplicate execution, Redis connectivity \|
37	\| Infrastructure \| Docker containers down, ports in use, env vars missing \|
38	\| Cross-cutting \| Data flows correctly in one layer but breaks in another \|
39
40	3. Check for quick context — run these in parallel:
41
42	```bash
43	# Recent changes that might have introduced the bug
44	git log --oneline -10
45	git diff HEAD~3 --stat
46
47	# Infrastructure health
48	docker compose ps
49	```
50
51	4. If the user provided a Sentry issue URL or error ID, query Sentry for the full stack trace and event details.
52	5. If the user mentions production errors, check PostHog error tracking for frequency and user impact.
53
54	State the triage result to the user:
55
56	> TRIAGE: [layer(s)] — Brief description of what appears to be happening.
57	</phase_1_triage>
58
59	<phase_2_execution_mode>
60	Based on the triage, decide the execution mode:
61
62	SINGLE-LAYER — The bug is isolated to one layer. Debug directly without dispatching agents.
63
64	MULTI-LAYER — The bug spans 2+ layers. Act as orchestrator and dispatch specialized debugging agents.
65
66	State the decision:
67
68	> EXECUTION MODE: SINGLE-LAYER — I will investigate and fix this directly.
69
70	OR
71
72	> EXECUTION MODE: MULTI-LAYER — I will dispatch specialized agents to investigate each layer in parallel.
73	</phase_2_execution_mode>
74
75	<phase_3_reproduce>
76	Reproduce the bug before investigating. Never fix what you can't reproduce.
77
78	<reproduction_strategies>
79
80	API bugs — Use curl or Bash to hit the endpoint directly:
81	```bash
82	# Discover the API base URL and endpoints from CLAUDE.md, package.json, or route files
83	curl -v http://localhost:<port>/<endpoint> \| jq .
84	```
85
86	Frontend bugs — Use browser automation MCPs:
87	1. Call `mcp__chrome-devtools__list_pages` or `mcp__plugin_playwright_playwright__browser_tabs` to check current state.
88	2. Navigate to the affected page and take a screenshot.
89	3. Check the browser console for errors.
90	4. Inspect network requests for failed API calls.
91
92	Queue/Worker bugs — Check Redis and BullMQ state:
93	```bash
94	# Check Redis connectivity
95	redis-cli ping
96
97	# Check queue state — discover the dev command from package.json scripts
98	# e.g., yarn dev, npm run dev, or the relevant workspace command
99	```
100
101	Database bugs — Query directly:
102	```bash
103	# Discover database credentials and container names from docker-compose.yml or .env
104	docker compose exec <db-container> psql -U <user> -c "SELECT * FROM ... LIMIT 5"
105	```
106
107	If reproduction fails, add strategic logging and retry. See references/debug-dispatch.md for logging patterns.
108	</reproduction_strategies>
109	</phase_3_reproduce>
110
111	<phase_4_investigate>
112	With the bug reproduced, investigate the root cause.
113
114	<single_layer_investigation>
115	Follow the data flow from the error point backward:
116
117	1. Read the source code at the error location.
118	2. Trace inputs — where does the data come from? What transformations happen?
119	3. Form a hypothesis about the root cause.
120	4. Test the hypothesis — add logging, inspect state, check the database.
121	5. If the hypothesis is wrong, form a new one based on what you learned.
122
123	Load relevant skills before diving in:
124	- Load skills matching the technologies used in the project (discover from package.json).
125	- Common examples: backend framewor

People who liked this also viewed

6 picks

Type