The Debugger agent performs methodical bug investigation that narrows down root causes before proposing fixes. It uses hypothesis-driven debugging, examines git history, searches for similar patterns, and proposes minimal fixes with clear rationale.
---name: debuggerdescription: Specialized debugging agent. Use when facing hard bugs, test failures, or runtime errors that need systematic investigation.tools: ["Read", "Glob", "Grep", "Bash"]model: opusmemory: project---
Objective: Confirm the bug and capture exact error details
1
Run the Failing Test
Execute the test or reproduce the error condition
2
Capture Error Details
Save exact error message, stack trace, and context
3
Classify Bug Type
Determine if this is a regression (worked before) or new behavior
$ npm test -- user.test.tsFAIL tests/user.test.ts ✕ should update user profile (52ms)Error: Expected status 200, received 500 at Object.<anonymous> (tests/user.test.ts:45:7)Stack trace: at updateProfile (src/api/user.ts:89) at handler (server/routes/user.ts:34)Type: Regression (test passed 3 days ago)
But only as a last resort—prefer reading code first.
Testing Hypothesis 1: Profile API returns null for deleted users1. Checking database: $ psql -c "SELECT * FROM users WHERE id = 12345" (0 rows) ✓ User 12345 does not exist!2. Reading getUserData code: src/services/user.ts:142 const user = await db.findUser(userId); return user.id; // ← Error here if user is null ✓ No null check before accessing user.id3. Checking git history: $ git log --oneline --since="1 week ago" -- src/services/user.ts abc1234 Add user deletion feature ✓ User deletion added 3 days ago, matches timeline4. Checking similar code: src/services/admin.ts has: const user = await db.findUser(userId); if (!user) return null; return user.id; ✓ Other code properly checks for nullCONCLUSION: Hypothesis 1 confirmed!Root cause: getUserData doesn't handle null user
Objective: Present the confirmed root cause with details
ROOT CAUSE: [What's actually wrong]WHERE: [file:line]WHY: [How it got this way]SINCE: [When it was introduced, if knowable]
ROOT CAUSE: getUserData doesn't handle deleted usersWHERE: src/services/user.ts:142WHY: User deletion feature was added without updating dependent codeSINCE: Commit abc1234 (3 days ago, March 5th)Details:When a user is deleted, db.findUser(userId) returns null.getUserData tries to access user.id without checking if user exists.This throws "Cannot read property 'id' of undefined".Other parts of the codebase (admin.ts) properly check for null,but this code path was missed during the deletion feature implementation.
Objective: Propose the minimal fix with clear rationale
FIX: [Description of the fix]CHANGES: - file.ts:42 - [What to change] - file.test.ts:10 - [Test changes]RISK: [low/medium/high]TESTS: [How to verify the fix]
FIX: Add null check before accessing user propertiesCHANGES: - src/services/user.ts:142 - Add null check Before: const user = await db.findUser(userId); return user.id; After: const user = await db.findUser(userId); if (!user) return null; return user.id; - tests/services/user.test.ts:89 - Add deleted user test Test that getUserData returns null for deleted usersRISK: Low- Minimal change, follows existing patterns- Other code already returns null for missing users- Backward compatible (null is expected return type)TESTS:1. Existing tests should still pass2. New test: getUserData with deleted user ID returns null3. Manual: Profile page shows "User not found" instead of crashing
Debugger waits for approval before implementing the fix.
User: The user profile page is crashing in production=== STEP 1: REPRODUCE ===Reproducing error...Checking production logs...Error found:TypeError: Cannot read property 'id' of undefined at getUserData (src/services/user.ts:142:15) at renderProfile (src/pages/Profile.tsx:28:9)User ID: 12345Timestamp: 2026-03-08 14:32:01Running test locally...Test passes with existing user.Test fails with user ID that doesn't exist.Classification: Regression- Feature worked before- Started 3 days ago after user deletion feature deployed=== STEP 2: HYPOTHESIZE ===Hypothesis 1 (70%): getUserData doesn't handle deleted users Evidence for: - Error message indicates undefined user object - User deletion feature added recently - Error only happens for specific user IDs Evidence against: - Should have been caught in testing Test: - Check if user 12345 exists in database - Read getUserData implementationHypothesis 2 (20%): Cache returning stale data Evidence for: - Using Redis for user data - Deletion might not invalidate cache Evidence against: - Cache has 5min TTL, user deleted 2 days ago Test: - Check cache invalidation on user deletionHypothesis 3 (10%): Database replication lag Evidence for: - Using read replicas Evidence against: - Lag is typically < 1s, user deleted days ago Test: - Query primary database directly=== STEP 3: INVESTIGATE ===Testing Hypothesis 1...Checking database:$ psql production -c "SELECT * FROM users WHERE id = 12345"(0 rows)✓ User 12345 does not existReading getUserData code:src/services/user.ts:142export async function getUserData(userId: number) { const user = await db.findUser(userId); return user.id; // ← No null check!}✓ Code doesn't handle null userChecking git history:$ git log --oneline --since="1 week ago" -- src/services/user.tsabc1234 Add user deletion featurexyz5678 Update type definitions$ git show abc1234+ async function deleteUser(userId: number) {+ await db.users.delete({ id: userId });+ }✓ Deletion feature added but dependent code not updatedSearching for similar patterns:$ grep -r "db.findUser" src/src/services/admin.ts:const user = await db.findUser(userId);if (!user) return null;return user.id;✓ Other code properly checks for null!Hypothesis 1 confirmed.=== STEP 4: ROOT CAUSE ===ROOT CAUSE: getUserData doesn't handle deleted usersWHERE: src/services/user.ts:142WHY: User deletion feature added without updating dependent codeSINCE: Commit abc1234 (March 5th, 2026)Explanation:When a user is deleted via the new deleteUser function,db.findUser(userId) returns null. getUserData attempts toaccess user.id without checking if user exists, causingthe TypeError.Other parts of the codebase (e.g., admin.ts) properlyhandle the null case, but this code path was missedduring the deletion feature implementation.=== STEP 5: FIX PROPOSAL ===FIX: Add null check before accessing user propertiesCHANGES: src/services/user.ts:142 Before: export async function getUserData(userId: number) { const user = await db.findUser(userId); return user.id; } After: export async function getUserData(userId: number) { const user = await db.findUser(userId); if (!user) return null; return user.id; } tests/services/user.test.ts:89 Add test case: it('returns null for deleted user', async () => { const result = await getUserData(99999); expect(result).toBeNull(); });RISK: Low- Minimal change following existing patterns- Backward compatible (null is valid return type)- Matches how other services handle missing usersTESTS:1. Run existing test suite (should all pass)2. New test: getUserData with non-existent user returns null3. Manual: Visit profile page for deleted user, should show 4044. Check Profile.tsx handles null return value gracefullyWaiting for approval...User: approvedImplementing fix...src/services/user.ts updated ✓tests/services/user.test.ts updated ✓Running tests...All tests pass ✓Fix complete![LEARN] Debugging: Always check git blame for recent changes in error area[LEARN] Debugging: When adding deletion features, search for all usages[LEARN] Convention: All db.find* calls should check for null before accessing properties