Bug Debugging Workflow

This guide covers the complete workflow for investigating and fixing bugs using Pointa and AI.

Overview

The bug debugging workflow:

Record Bug → AI Investigates → Implement Fix → Test → Resolve
        ↑                              ↓
        └──── Add Logging (if needed) ←┘

Phase 1: Record the Bug

Prepare to Reproduce

Before recording:

  1. Identify clear steps to trigger the bug
  2. Start from a known state (fresh page load)
  3. Know what the expected vs. actual behavior is

Start Recording

  1. Open the Pointa sidebar
  2. Click the Report Issue button
  3. Recording indicator appears (max 30 seconds)

Reproduce the Bug

Carefully perform the steps that trigger the bug:

  • Click through the exact flow
  • Enter the same data
  • Wait for the same conditions

Stop and Submit

  1. Click Stop Recording
  2. Fill in the bug description:
    • Title: Brief summary
    • Expected: What should have happened
    • Actual: What actually happened
    • Steps: If not obvious from the recording
  3. Submit

Phase 2: AI Investigation

Ask AI to Investigate

Switch to your AI tool:

Effective prompts:

  • "Check Pointa for bug reports and investigate"
  • "There's a bug report in Pointa - analyze it"
  • "Investigate the Pointa bug and identify the root cause"

What AI Does

  1. Calls read_issue_reports to get the bug timeline
  2. Analyzes console errors and stack traces
  3. Reviews network request failures
  4. Traces user interactions
  5. Examines relevant code

AI May Ask for More Information

If AI can't identify the root cause, it might:

  • Ask clarifying questions
  • Request you add logging
  • Suggest checking specific conditions

Phase 3: Debugging Iteration (If Needed)

Sometimes the first recording doesn't capture enough information.

AI Adds Logging

AI may add debug statements:

console.log('[DEBUG] User state:', userState);
console.log('[DEBUG] API response:', response);

Mark for Re-Run

AI calls mark_issue_needs_rerun which:

  • Adds debugging notes
  • Changes status to "debugging"
  • Prepares for a new recording

Record Again

  1. Refresh your page to load the new logging
  2. Start a new bug recording
  3. Reproduce the bug again
  4. The new logs will be captured

AI Analyzes New Data

With additional logging, AI has more context to identify the root cause.

Phase 4: Fix Implementation

AI Implements the Fix

Once root cause is identified:

  1. AI modifies the relevant code
  2. Explains the fix approach
  3. Calls mark_issue_for_review

What AI Provides

  • Description of the root cause
  • Explanation of the fix
  • Files that were modified
  • Any side effects to watch for

Phase 5: Test and Resolve

Test the Fix

  1. Refresh your development page
  2. Try to reproduce the original bug
  3. Verify it no longer occurs
  4. Check for side effects

If Fixed

The bug is resolved:

  1. Confirm the fix works
  2. AI marks it as resolved
  3. Report is archived

If Not Fixed

Iterate:

  1. Explain what's still wrong
  2. AI investigates further
  3. Additional fixes are applied
  4. Test again

Using Backend Logs

For full-stack bugs, run your dev server via pointa dev:

npx pointa-server dev npm run dev

Now your bug recordings include server-side logs, giving AI visibility into:

  • API request handling
  • Database queries
  • Server-side errors
  • Authentication flows

See Backend Logging for setup details.

Tips for Effective Bug Reports

Be Precise with Reproduction

The cleaner your reproduction, the easier for AI:

  • Minimal steps
  • Consistent reproduction
  • Clear trigger point

Describe Expected Behavior

AI needs to know what "correct" looks like:

  • "Should show success message"
  • "Should redirect to dashboard"
  • "Should update the total"

Note Intermittent Bugs

For bugs that don't always happen:

  • Note the frequency ("happens ~50% of the time")
  • Describe any patterns you've noticed
  • Include timing information if relevant

Include Environment Details

Sometimes relevant:

  • Browser version
  • Screen size
  • User state (logged in, specific role)
  • Data conditions

Common Bug Patterns

Null Reference Errors

Timeline shows:

[Error] Cannot read property 'x' of undefined

AI approach: Find where the value should be set, add null checks.

Network Failures

Timeline shows:

[Network] GET /api/data → 500 Error

AI approach: Check backend logs, investigate API handler.

State Mismatches

Timeline shows:

[Click] Submit
[Log] Form state: { submitted: false }  // Should be true

AI approach: Trace state updates, find timing issues.

Race Conditions

Timeline shows:

[Network] GET /api/user → pending
[Click] Dashboard link
[Error] User not loaded

AI approach: Add loading states, wait for data.

Related