From ts-dev-kit
Triages, reproduces, and fixes full-stack bugs across frontend, API, DB, queues, and infra using multi-agent orchestration and git/docker checks. For runtime errors, failed flows, or Sentry/PostHog issues.
npx claudepluginhub jgamaraalv/ts-dev-kit --plugin ts-dev-kit[error-description or sentry-issue-url]This skill is limited to using the following tools:
<live_context>
Guides systematic debugging for broken features, errors, failed deployments, or tests: reproduce bugs, gather git/logs diagnostics, read errors, diagnose root causes before fixes.
Enforces systematic root cause analysis for bugs, test failures, unexpected behavior, and regressions via five-phase workflow: Understand, Reproduce, Isolate, Fix, Verify.
Investigates and diagnoses software bugs using scientific method: observe symptoms, hypothesize causes, test with logging/Bash/Grep/Glob, analyze without fixing. Use before /fix for root cause.
Share bugs, ideas, or general feedback.
<live_context>
Recent git changes (regression candidates):
!git log --oneline -10 2>/dev/null || echo "(not a git repo)"
Working tree status:
!git status --short 2>/dev/null || echo "(not a git repo)"
</live_context>
<trigger_examples>
<phase_1_triage> Classify the bug before investigating. This determines which agents to dispatch.
| Layer | Signals |
|---|---|
| Frontend | UI doesn't render, hydration errors, blank pages, console errors, wrong data displayed |
| API | HTTP error codes (4xx/5xx), validation failures, timeout, wrong response body |
| Database | Missing data, wrong query results, migration issues, connection errors |
| Queue/Worker | Jobs stuck, not processing, duplicate execution, Redis connectivity |
| Infrastructure | Docker containers down, ports in use, env vars missing |
| Cross-cutting | Data flows correctly in one layer but breaks in another |
# Recent changes that might have introduced the bug
git log --oneline -10
git diff HEAD~3 --stat
# Infrastructure health
docker compose ps
State the triage result to the user:
TRIAGE: [layer(s)] — Brief description of what appears to be happening. </phase_1_triage>
<phase_2_execution_mode> Based on the triage, decide the execution mode:
SINGLE-LAYER — The bug is isolated to one layer. Debug directly without dispatching agents.
MULTI-LAYER — The bug spans 2+ layers. Act as orchestrator and dispatch specialized debugging agents.
State the decision:
EXECUTION MODE: SINGLE-LAYER — I will investigate and fix this directly.
OR
EXECUTION MODE: MULTI-LAYER — I will dispatch specialized agents to investigate each layer in parallel. </phase_2_execution_mode>
<phase_3_reproduce> Reproduce the bug before investigating. Never fix what you can't reproduce.
<reproduction_strategies>
API bugs — Use curl or Bash to hit the endpoint directly:
# Discover the API base URL and endpoints from CLAUDE.md, package.json, or route files
curl -v http://localhost:<port>/<endpoint> | jq .
Frontend bugs — Use browser automation MCPs:
mcp__chrome-devtools__list_pages or mcp__plugin_playwright_playwright__browser_tabs to check current state.Queue/Worker bugs — Check Redis and BullMQ state:
# Check Redis connectivity
redis-cli ping
# Check queue state — discover the dev command from package.json scripts
# e.g., yarn dev, npm run dev, or the relevant workspace command
Database bugs — Query directly:
# Discover database credentials and container names from docker-compose.yml or .env
docker compose exec <db-container> psql -U <user> -c "SELECT * FROM ... LIMIT 5"
If reproduction fails, add strategic logging and retry. See references/debug-dispatch.md for logging patterns. </reproduction_strategies> </phase_3_reproduce>
<phase_4_investigate> With the bug reproduced, investigate the root cause.
<single_layer_investigation> Follow the data flow from the error point backward:
Load relevant skills before diving in:
When the bug involves library API misuse, version-specific behavior, or unclear method signatures, query Context7 for up-to-date documentation:
mcp__context7__resolve-library-id — resolve the library name (e.g., "fastify", "drizzle-orm", "bullmq") to its Context7 ID.mcp__context7__query-docs — query with the specific API, method, or error message you're investigating.Use Context7 when:
<multi_layer_investigation> Dispatch specialized agents in parallel. Each agent investigates its layer independently and reports findings.
See references/debug-dispatch.md for the agent prompt templates and dispatch patterns.
<debugging_roles>
| Role | Agent type | Domain | MCPs |
|---|---|---|---|
| Backend debugger | debugger | API routes, use cases, DB queries, server hooks | Sentry, PostHog, Context7 |
| Frontend debugger | debugger | Pages, components, client state, network | Chrome DevTools, Playwright, Context7 |
| Queue debugger | debugger | Job queues, workers, Redis state | Context7 |
| E2E verifier | playwright-expert | Reproduce and verify via browser automation | Playwright |
Each debugging agent should use Context7 (mcp__context7__resolve-library-id + mcp__context7__query-docs) to verify library API usage when the bug involves unclear method signatures, version-specific behavior, or suspected API misuse. Include this instruction in agent prompts — see references/debug-dispatch.md.
</debugging_roles>
<dispatch_rules>
<model_selection>
haikusonnetopus
</model_selection>
</multi_layer_investigation>
</phase_4_investigate><phase_5_fix> Implement the minimal fix that addresses the root cause.
<fix_principles>
<fix_dispatch> In MULTI-LAYER mode, the orchestrator decides who fixes what:
<phase_6_verify> A fix is not done until it's verified end-to-end.
tsc, lint, test).If any step fails, return to phase 5 and fix the issue. Re-run all verification steps from the beginning. </phase_6_verify>
<common_patterns> Quick reference for the most frequent bugs in this stack. Use these to accelerate triage.
Frontend → API boundary
API → Database boundary
API → Redis/Queue boundary
Frontend rendering
Do not add explanations, caveats, or follow-up suggestions unless the user asks.