@jgamaraalv/ts-dev-kit 1.2.1 → 2.1.0

package/skills/debug/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: debug
+description: "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 via Sentry/PostHog, (4) tracing data flow across backend and frontend, or (5) the user reports a bug that spans multiple layers."
+argument-hint: "[error-description or sentry-issue-url]"
+---
+
+<trigger_examples>
+- "Debug why the form submission fails with a 500 error"
+- "The dashboard page shows a blank screen after login"
+- "API returns 403 but the user should be authorized"
+- "Investigate this Sentry issue: PROJECT-123"
+- "The form submits but nothing appears in the list"
+- "Debug the notification queue — jobs are stuck"
+</trigger_examples>
+
+<workflow>
+Follow each phase in order. Each one feeds the next.
+
+<phase_1_triage>
+Classify the bug before investigating. This determines which agents to dispatch.
+
+1. Read the error description, stack trace, or reproduction steps provided by the user.
+2. Determine the affected layers:
+
+| 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 |
+
+3. Check for quick context — run these in parallel:
+
+```bash
+# Recent changes that might have introduced the bug
+git log --oneline -10
+git diff HEAD~3 --stat
+
+# Infrastructure health
+docker compose ps
+```
+
+4. If the user provided a Sentry issue URL or error ID, query Sentry for the full stack trace and event details.
+5. If the user mentions production errors, check PostHog error tracking for frequency and user impact.
+
+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:
+```bash
+# 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:
+1. Call `mcp__chrome-devtools__list_pages` or `mcp__plugin_playwright_playwright__browser_tabs` to check current state.
+2. Navigate to the affected page and take a screenshot.
+3. Check the browser console for errors.
+4. Inspect network requests for failed API calls.
+
+**Queue/Worker bugs** — Check Redis and BullMQ state:
+```bash
+# 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:
+```bash
+# 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:
+
+1. Read the source code at the error location.
+2. Trace inputs — where does the data come from? What transformations happen?
+3. Form a hypothesis about the root cause.
+4. Test the hypothesis — add logging, inspect state, check the database.
+5. If the hypothesis is wrong, form a new one based on what you learned.
+
+Load relevant skills before diving in:
+- Load skills matching the technologies used in the project (discover from package.json).
+- Common examples: backend framework skills, ORM/database skills, frontend framework skills, queue/worker skills.
+- Read CLAUDE.md and package.json to identify the project's tech stack before selecting skills.
+
+When the bug involves library API misuse, version-specific behavior, or unclear method signatures, query Context7 for up-to-date documentation:
+1. `mcp__context7__resolve-library-id` — resolve the library name (e.g., "fastify", "drizzle-orm", "bullmq") to its Context7 ID.
+2. `mcp__context7__query-docs` — query with the specific API, method, or error message you're investigating.
+
+Use Context7 when:
+- The error message references a library API you're unsure about.
+- You suspect a breaking change between versions (check the project's package.json for installed versions first).
+- The stack trace points to library internals and you need to understand expected behavior.
+- You need to verify correct usage patterns for any project dependency.
+</single_layer_investigation>
+
+<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>
+1. Launch layer-specific debuggers in parallel — they investigate independently.
+2. Each agent receives: the error description, reproduction steps, relevant file paths, and which skills to load.
+3. Each agent reports: root cause hypothesis, evidence (logs, screenshots, stack traces), and suggested fix location.
+4. After all agents report, correlate findings — the root cause often lives at the boundary between layers.
+5. If agents disagree on the root cause, investigate the boundary between their domains.
+</dispatch_rules>
+
+<model_selection>
+- Simple, well-scoped investigation (single file, clear error) → `haiku`
+- Moderate investigation (multiple files, data flow tracing) → `sonnet`
+- Complex cross-cutting investigation (race conditions, auth flows, distributed state) → `opus`
+</model_selection>
+</multi_layer_investigation>
+</phase_4_investigate>
+
+<phase_5_fix>
+Implement the minimal fix that addresses the root cause.
+
+<fix_principles>
+- Fix the root cause, not the symptom. A 500 error caused by a missing null check needs the null check AND proper error handling upstream.
+- Follow existing patterns. Read similar code in the codebase before writing the fix.
+- Load the relevant skills before writing the fix (same skills as investigation phase).
+- If the fix spans multiple layers, dispatch agents for each layer. See references/debug-dispatch.md for the fix dispatch template.
+</fix_principles>
+
+<fix_dispatch>
+In MULTI-LAYER mode, the orchestrator decides who fixes what:
+1. Identify which files need changes based on investigation findings.
+2. Group changes by package/domain.
+3. Determine dependency order (shared → api → web).
+4. Dispatch fix agents sequentially if there are dependencies, or in parallel if independent.
+</fix_dispatch>
+</phase_5_fix>
+
+<phase_6_verify>
+A fix is not done until it's verified end-to-end.
+
+1. **Re-run the reproduction** — the original error should no longer occur.
+2. **Quality gates** — run the project's type checking, linting, and testing commands for every affected package. Discover available commands from package.json scripts (e.g., `tsc`, `lint`, `test`).
+3. **Browser verification** (for user-facing bugs) — use Playwright or Chrome DevTools to navigate to the affected page and confirm the fix works visually.
+4. **Regression check** — verify the fix doesn't break related functionality. Run the full test suite for affected packages.
+
+If any step fails, return to phase 5 and fix the issue. Re-run all verification steps from the beginning.
+</phase_6_verify>
+</workflow>
+
+<common_patterns>
+Quick reference for the most frequent bugs in this stack. Use these to accelerate triage.
+
+**Frontend → API boundary**
+- CORS errors → check server CORS config
+- 401/403 → check auth middleware, token expiry, cookie settings
+- Wrong data shape → compare shared schema/type definitions with API response
+
+**API → Database boundary**
+- "relation does not exist" → migration not applied
+- Empty results → wrong query conditions, check WHERE clause
+- Connection errors → Docker not running, pool exhausted
+
+**API → Redis/Queue boundary**
+- Jobs not processing → worker not started, Redis down, wrong queue name
+- Duplicate jobs → missing deduplication, idempotency key
+- Stalled jobs → worker crashed without ack, check stall interval
+
+**Frontend rendering**
+- Hydration mismatch → server/client content differs, date formatting, conditional rendering
+- Blank page → unhandled error in RSC, check error.tsx boundaries
+- Infinite loading → API call hanging, missing Suspense boundary
+</common_patterns>
+
+<output>
+When complete, produce a debug report:
+
+```
+## Bug resolved
+
+**Root cause**: one sentence describing why the bug occurred.
+**Fix**: one sentence describing what was changed to fix it.
+
+### Investigation path
+Brief trace of how the root cause was found (which layer, what evidence).
+
+### Files changed
+List every file created/modified.
+
+### Verification
+- Reproduction: pass (the original error no longer occurs)
+- tsc: pass/fail (per package)
+- lint: pass/fail (per package)
+- test: pass/fail (per package)
+- Browser: pass/fail (if applicable)
+
+### Skills loaded
+List every Skill() call made.
+
+### MCPs used
+List every MCP used, or "none".
+```
+
+Do not add explanations, caveats, or follow-up suggestions unless the user asks.
+</output>
+
+<task>
+$ARGUMENTS
+</task>

package/skills/debug/references/debug-dispatch.md

@@ -0,0 +1,289 @@
+# Debug Agent Dispatch Reference
+
+## Table of contents
+
+- [Investigation agent template](#investigation-agent-template)
+- [Fix agent template](#fix-agent-template)
+- [Role-specific prompts](#role-specific-prompts)
+- [Dispatch examples](#dispatch-examples)
+- [Strategic logging patterns](#strategic-logging-patterns)
+- [Correlation protocol](#correlation-protocol)
+
+---
+
+## Investigation agent template
+
+The `debugger` agent already includes project context, common errors, debugging commands, strategic logging, and quality gates in its system prompt. The dispatch prompt only needs **bug-specific** information:
+
+```
+## Bug description
+[What the user reported — error message, behavior, reproduction steps]
+
+## Your investigation scope
+[Which layer/files to investigate. Be specific about boundaries.]
+
+## Skills to load
+Call the Skill tool before investigating:
+- Skill(skill: "[skill-1]")
+- Skill(skill: "[skill-2]")
+
+## Reproduction context
+[How the bug was reproduced — curl command, browser steps, log output]
+
+## Files to start with
+[List specific file paths where the error originates or is likely rooted]
+
+## Report format
+When done, report:
+- **Root cause hypothesis**: one sentence.
+- **Evidence**: what you found that supports the hypothesis.
+- **Fix location**: which file(s) and line(s) need to change.
+- **Suggested fix**: code diff or description.
+- **Confidence**: high / medium / low.
+```
+
+### Skill mapping for investigation
+
+The debugger loads skills dynamically based on the bug domain. Include the appropriate skills in the dispatch prompt:
+
+| Bug domain | Skills to load |
+|-----------|---------------|
+| API/Fastify | `fastify-best-practices` |
+| Database | `drizzle-pg`, `postgresql` |
+| Frontend/React | `nextjs-best-practices`, `react-best-practices` |
+| Queue/Redis | `bullmq`, `ioredis` |
+| Security | `owasp-security-review` |
+
+## Fix agent template
+
+After investigation, dispatch the appropriate **specialist agent** (not necessarily the debugger) to implement fixes. Specialist agents already include their domain context and quality gates:
+
+```
+## Bug root cause
+[One sentence from the investigation phase]
+
+## Your fix scope
+[Which files to modify and what the fix should do]
+
+## Existing patterns to follow
+[Paste relevant code snippets or file paths showing the codebase conventions]
+
+## Fix requirements
+[Specific changes needed — be precise about expected behavior]
+```
+
+Use the agent type that matches the fix domain:
+- API route fix -> `api-builder` (preloads fastify-best-practices)
+- Database/query fix -> `database-expert` (preloads drizzle-pg, postgresql)
+- Component fix -> `react-specialist` (preloads react-best-practices, composition-patterns)
+- Type fix -> `typescript-pro`
+- Security fix -> `security-scanner` (preloads owasp-security-review)
+- Cross-cutting or unclear -> `debugger` (load skills dynamically)
+
+---
+
+## Role-specific prompts
+
+### Backend debugger
+
+**Agent type**: `debugger`
+**Skills to include**: `fastify-best-practices`, `drizzle-pg`, `postgresql`
+**Scope**: Backend source directory — routes, use cases, adapters, plugins, middleware. Discover the path from the project structure.
+
+Investigation focus:
+- Read the Fastify route handler at the error location
+- Check request validation (Zod schema vs actual payload)
+- Trace database queries — use `EXPLAIN ANALYZE` if performance-related
+- Check error handling — are errors caught and mapped to proper HTTP codes?
+- Inspect middleware/hooks in the request lifecycle
+
+### Frontend debugger
+
+**Agent type**: `debugger`
+**Skills to include**: `nextjs-best-practices`, `react-best-practices`
+**Scope**: Frontend source directory — pages, components, hooks, contexts, lib. Discover the path from the project structure.
+
+Investigation focus:
+- Check the page/component at the error location
+- Inspect browser console for client-side errors (use Chrome DevTools or Playwright MCP)
+- Check network requests — is the API call correct? Does the response match expectations?
+- Verify server vs client rendering — hydration mismatches, missing Suspense boundaries
+- Check auth context — is the user authenticated? Are tokens being sent?
+
+MCPs available to the debugger:
+- `mcp__chrome-devtools__take_screenshot` — visual state of the page
+- `mcp__chrome-devtools__list_console_messages` — browser console errors
+- `mcp__chrome-devtools__list_network_requests` — failed API calls
+- `mcp__plugin_playwright_playwright__browser_snapshot` — accessibility tree inspection
+
+### Queue debugger
+
+**Agent type**: `debugger`
+**Skills to include**: `bullmq`, `ioredis`
+**Scope**: Queue/worker source directory — queue definitions, workers, job processors. Discover the path from the project structure.
+
+Investigation focus:
+- Check queue configuration (name, connection, default job options)
+- Inspect worker concurrency and error handling
+- Check Redis connectivity and key patterns
+- Look for stalled jobs, failed jobs, or jobs stuck in "waiting"
+- Verify job data shape matches worker expectations
+
+### E2E verifier
+
+**Agent type**: `playwright-expert`
+**Skills**: none needed (agent has its own testing patterns)
+**Scope**: Full application via browser automation
+
+Verification focus:
+- Navigate to the affected page
+- Perform the user flow that triggers the bug
+- Take screenshots before and after
+- Check console for errors
+- Verify the fix resolves the issue visually
+
+---
+
+## Dispatch examples
+
+### Example 1: API returns 500 on resource creation
+
+```
+# Triage: API layer (single-layer)
+# No dispatch needed — debug directly
+
+1. curl the endpoint to reproduce
+2. Read the route handler and use case
+3. Check the database query
+4. Fix the root cause
+5. Verify with curl + tests
+```
+
+### Example 2: Form submits but data doesn't appear in list
+
+```
+# Triage: Cross-cutting (frontend -> API -> database)
+# Dispatch: MULTI-LAYER
+
+# Wave 1: Parallel investigation
+Task(
+  description: "Debug resource creation API endpoint",
+  subagent_type: "debugger",
+  model: "sonnet",
+  prompt: """
+## Bug description
+User submits the creation form successfully (200 response) but the item
+doesn't appear in the list page.
+
+## Your investigation scope
+Backend only: the POST endpoint and corresponding GET list endpoint.
+Check if data reaches the database and if the list query returns it.
+
+## Skills to load
+Call the Skill tool before investigating:
+- Load skills matching the backend framework and ORM used (discover from package.json)
+
+## Reproduction context
+curl -X POST http://localhost:<port>/api/<resource> -H "Content-Type: application/json" \
+  -d '{"field":"value"}'
+Returns 200, but GET /api/<resource> returns empty array.
+
+## Files to start with
+- Discover from the project structure: look for route handlers, use cases, and persistence layers
+"""
+)
+
+Task(
+  description: "Debug resource list page",
+  subagent_type: "debugger",
+  model: "sonnet",
+  prompt: """
+## Bug description
+User submits the creation form successfully but the item doesn't appear
+in the list page.
+
+## Your investigation scope
+Frontend only: the list page. Check the API call and rendering logic.
+
+## Skills to load
+Call the Skill tool before investigating:
+- Load skills matching the frontend framework used (discover from package.json)
+
+## Reproduction context
+Navigate to the list page after submitting the form. The list shows empty or
+stale data.
+
+## Files to start with
+- Discover from the project structure: look for the list page component and its sub-components
+"""
+)
+
+# Wave 2: Dispatch fixes using specialist agents matching the fix domain
+# e.g., api-builder for API fix, react-specialist for frontend fix
+
+# Wave 3: E2E verification
+Task(
+  description: "Verify resource creation flow",
+  subagent_type: "playwright-expert",
+  model: "haiku",
+  prompt: """
+## Your task
+Verify the resource creation flow works end-to-end:
+1. Navigate to the creation form
+2. Fill in the required fields and submit
+3. Verify the new item appears in the list page
+
+## Success criteria
+- Form submits successfully
+- Item appears in the list within 5 seconds
+- No console errors
+"""
+)
+```
+
+### Example 3: Production error from Sentry
+
+```
+# Triage: Starts with Sentry context, then investigate
+
+1. Query Sentry for the full stack trace and event details
+2. Identify the affected layer from the stack trace
+3. Dispatch investigation agent(s) for that layer
+4. Dispatch fix agent(s) using the appropriate specialist
+5. E2E verification
+```
+
+---
+
+## Strategic logging patterns
+
+When investigation needs more visibility, add temporary logging:
+
+```typescript
+// Prefix with DEBUG: for easy cleanup after fixing
+request.log.debug({ body: request.body, params: request.params }, "DEBUG: incoming request");
+request.log.debug({ result }, "DEBUG: query result");
+
+// Outside request context
+fastify.log.debug({ config }, "DEBUG: plugin configuration");
+```
+
+After fixing, search and remove all `DEBUG:` log lines:
+```bash
+# Search the backend source directory for temporary debug lines
+grep -rn "DEBUG:" <backend-src-dir>/
+```
+
+---
+
+## Correlation protocol
+
+When multiple agents investigate the same bug, the orchestrator correlates their findings:
+
+1. Collect each agent's root cause hypothesis and evidence.
+2. Check for consistency — do the hypotheses align?
+3. If agents agree, proceed with the fix.
+4. If agents disagree, look at the boundary:
+   - Frontend says "API returns wrong data" + Backend says "query is correct" -> check response serialization.
+   - Backend says "data is correct in DB" + Frontend says "list is empty" -> check API response shape vs frontend expectations (Zod schema mismatch).
+5. The true root cause is usually at the boundary between layers where one side's assumption doesn't match the other's reality.