Debugging strategies

Skill BAKUGOS1/SkilledAgents-Toolkit/plugins/skilled-agents/skills/debugging-strategies

Portable open-source Codex toolkit with reusable skills, custom agents, plugins, project profiles, validation tools, and SDK examples.

Install

npx -y skills add BAKUGOS1/SkilledAgents-Toolkit --skill debugging-strategies

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Systematic debugging for Wrkly's full-stack TypeScript monorepo — reproduce, trace, fix, verify.

SKILL.md

3.2 KB, as published. Nobody here has run it

Debugging Strategies — Wrkly Edition

Transform debugging from guesswork into systematic problem-solving.

When to Use

Tracking down elusive bugs in frontend or backend
Investigating performance issues (slow queries, re-renders)
Debugging production incidents on Railway/Vercel
Analyzing Socket.io realtime sync issues
Debugging auth/JWT token problems

The Debug Loop

1. Reproduce

Backend: Check Fastify logs (app.log.info/error)
Frontend: Check browser console + Next.js terminal
Database: Run npx prisma studio to inspect data state
Realtime: Check Socket.io connection in browser DevTools → Network → WS

2. Isolate the Layer

Symptom	Layer	Start Here
4xx/5xx API response	Route handler	`wrkly-api/src/routes/{resource}.ts`
Data not showing	Prisma query	Check `select:` fields, `isArchived` filter
Auth failure	JWT middleware	`wrkly-api/src/middleware/auth.ts`
Stale UI data	React Query cache	Check `queryKey`, `staleTime`, invalidation
Realtime not updating	Socket.io	`wrkly-api/src/lib/socket.ts` → event names
Styling broken	CSS tokens	`globals.css` dark/light mode variables

3. Form Hypothesis

Before touching code, state: "I think X is happening because Y, and I can verify by Z."

4. Binary Search

Comment out half the suspicious code
Does the bug persist? → Problem is in the remaining half
Repeat until you find the exact line

5. Common Wrkly Bugs

Prisma: Missing data

// ❌ Bug: cards not showing
prisma.board.findUnique({ where: { id: boardId } })
// ✅ Fix: add select with nested relations
prisma.board.findUnique({
  where: { id: boardId },
  select: { lists: { select: { cards: { where: { isArchived: false } } } } }
})

Auth: 401 on valid token

// Check: is authenticate middleware registered?
app.post('/endpoint', { preHandler: [authenticate] }, handler)
// Check: is JWT_SECRET the same between token generation and verification?

React Query: Stale data after mutation

// ❌ Bug: list doesn't update after creating card
// ✅ Fix: invalidate the right query key
queryClient.invalidateQueries({ queryKey: ['board', boardId] })

Socket.io: Events not received

// Check: is the client subscribing to the correct room?
socket.emit('join-board', boardId)
// Check: is the server emitting to the right room?
io.to(`board:${boardId}`).emit('card:created', data)

6. Fix and Verify

Write a failing test that reproduces the bug
Apply the minimal fix
Run cd wrkly-api && pnpm test — all green
Run cd wrkly-web && pnpm build — no type errors
Manually verify the fix in the browser

7. Document

Add a comment explaining WHY the fix works, not WHAT it does:

// Fix: must filter by isArchived because soft-deleted cards were
// appearing in the board view count (issue #42)
where: { isArchived: false }