type	skill
name	Bug Investigation
description	Systematic bug investigation and root cause analysis
skillSlug	bug-investigation
phases	["E","V"]
generated	"2026-03-02T00:00:00.000Z"
status	filled
scaffoldVersion	2.0.0

Bug Investigation

When to Use

Activate this skill when investigating a bug report, error message, or unexpected behavior. It provides a systematic approach to root cause analysis.

Instructions

Reproduce the bug:
- Identify the exact steps to trigger the issue.
- Note the environment: which backend (Express/NestJS)? Which frontend (Next.js/SvelteKit)?
- Capture the error message, HTTP status code, or unexpected UI behavior.
Classify the bug:
- API error (4xx/5xx): Check backend logs, route handlers, service methods, SQL queries.
- Auth error (401): Check Clerk token retrieval, Bearer header attachment, guard/middleware config.
- UI error: Check component state, API client response parsing, rendering logic.
- Data error: Check DB schema, column mapping (snake_case → camelCase), seed data.
Trace the data flow:
- Frontend: page.tsx/+page.svelte → lib/api.ts → HTTP request
- Backend: Middleware → Route/Controller → Service → Database → Response
- Identify which layer the bug originates from.
Check both implementations:
- Does the bug exist in both Express and NestJS?
- Does the bug exist in both Next.js and SvelteKit?
- If only one implementation is affected, the bug is in implementation-specific code.
Apply the fix:
- Make the smallest possible change to resolve the issue.
- Fix in all affected implementations.
- Test the fix end-to-end.
Prevent regression:
- Suggest a test case that would catch this bug.
- Update documentation if the bug revealed a misunderstanding.
Legacy project triage: For bugs in legacy projects (Express/Next.js), only critical issues warrant fixes. Non-critical bugs should be documented for reference but not fixed, as these projects are in maintenance-only mode. Prioritize investigating and fixing bugs in the active stack (NestJS/SvelteKit).

Examples

API 500 error investigation:

Symptom: POST /api/franchises returns 500
Trace: Controller receives request → Service.create() called → SQL INSERT fails
Root cause: Missing NOT NULL column 'owner_name' in INSERT statement
Fix: Add owner_name to the INSERT query in both backends
Test: POST with valid data should return 201; POST without owner_name should return 400

UI state bug investigation:

Symptom: Dashboard shows stale data after creating a franchise
Trace: NewFranchisePage → createFranchise() → redirect to /dashboard → page loads cached data
Root cause: Dashboard page doesn't refetch on navigation (Next.js client-side cache)
Fix: Add cache invalidation or force refetch on dashboard mount

Bug Investigation

When to Use

Activate this skill when investigating a bug report, error message, or unexpected behavior. It provides a systematic approach to root cause analysis.

Instructions

Reproduce the bug:

Identify the exact steps to trigger the issue.
Note the environment: which backend (Express/NestJS)? Which frontend (Next.js/SvelteKit)?
Capture the error message, HTTP status code, or unexpected UI behavior.

Classify the bug:

API error (4xx/5xx): Check backend logs, route handlers, service methods, SQL queries.
Auth error (401): Check Clerk token retrieval, Bearer header attachment, guard/middleware config.
UI error: Check component state, API client response parsing, rendering logic.
Data error: Check DB schema, column mapping (snake_case → camelCase), seed data.

Trace the data flow:

Frontend: page.tsx/+page.svelte → lib/api.ts → HTTP request
Backend: Middleware → Route/Controller → Service → Database → Response
Identify which layer the bug originates from.

Check both implementations:

Does the bug exist in both Express and NestJS?
Does the bug exist in both Next.js and SvelteKit?
If only one implementation is affected, the bug is in implementation-specific code.

Apply the fix:

Make the smallest possible change to resolve the issue.
Fix in all affected implementations.
Test the fix end-to-end.

Prevent regression:

Suggest a test case that would catch this bug.
Update documentation if the bug revealed a misunderstanding.

Legacy project triage: For bugs in legacy projects (Express/Next.js), only critical issues warrant fixes. Non-critical bugs should be documented for reference but not fixed, as these projects are in maintenance-only mode. Prioritize investigating and fixing bugs in the active stack (NestJS/SvelteKit).

Examples

API 500 error investigation:

Symptom: POST /api/franchises returns 500 Trace: Controller receives request → Service.create() called → SQL INSERT fails Root cause: Missing NOT NULL column 'owner_name' in INSERT statement Fix: Add owner_name to the INSERT query in both backends Test: POST with valid data should return 201; POST without owner_name should return 400

UI state bug investigation:

Symptom: Dashboard shows stale data after creating a franchise Trace: NewFranchisePage → createFranchise() → redirect to /dashboard → page loads cached data Root cause: Dashboard page doesn't refetch on navigation (Next.js client-side cache) Fix: Add cache invalidation or force refetch on dashboard mount

bug-investigation