Skip to content

Debug an Issue

In this tutorial, you'll use the Debug agent to trace a reported issue to its origin in the knowledge graph and get a fix at the source — not a symptom patch.

Prerequisites

  • Potpie CLI installed and set up (Quickstart)
  • A repository registered and parsed to ready status

Steps

1. Describe the issue

Paste an error message, stack trace, or describe the unexpected behavior. Include any context about when it occurs.

> "Users are getting a 500 error when trying to reset their password.
>  The error log shows: NoneType has no attribute 'email'"

Tip

Follow-up messages within the same session retain full context. Start with a high-level symptom and narrow to the root cause across subsequent turns.

2. Let Debug investigate

The Debug agent applies its eight-step methodology automatically:

  1. Understand and validate — confirms the reported behavior against the codebase
  2. Explore and hypothesize — traverses relevant code paths in the knowledge graph
  3. Identify root cause — pins the failure to a specific file and line
  4. Generalize — checks if the same pattern appears elsewhere
  5. Design solution — generates a targeted fix scoped to the root cause
  6. Scrutinize — evaluates against edge cases and traces side effects
  7. Implement — produces corrected code with exact file paths
  8. Verify — validates the fix against the original failure

3. Review the result

Debug returns:

  • The root cause traced to its true origin
  • A mapped path from origin to symptom
  • A fix that resolves the underlying issue (not just the reported instance)

Key principles

Warning

User-reported symptoms and suggested fixes are treated as starting points for investigation, not conclusions. The real issue is often upstream of where the problem surfaces.

  • A fix at the source prevents the problem for every downstream caller
  • A fix at the symptom only handles one path
  • Debug always identifies which type of fix it's applying and why

Example scenarios

Scenario What Debug traces
Null pointer exception Through service and data layers to the missing initialization
Memory leak Through object lifecycle and dependency chains to the source
Race condition Through concurrent access paths to the unprotected shared state
Auth bypass Through middleware chain to the misconfigured route

Next steps