debug-issue

name	debug-issue
description	Use when encountering unexpected behavior, failing tests, API errors, or runtime panics in Tundra — before proposing any fix

Debug Issue

Overview

Graph-powered debugging traces call chains and recent changes in seconds. Random guessing on a codebase this size wastes hours.

Core principle: Understand before fixing. A wrong fix in auth, crypto, or migrations can corrupt data or create security holes.

When to Use

• Test failure with unclear root cause
• API returning wrong status or body
• Panel route not rendering / navigation broken
• Rust compilation error involving multiple crates
• Docker dev stack behaving differently than expected

The Process

Step 1: Get minimal context

get_minimal_context(task="debug <symptom description>")

Always first. Orients graph for your specific investigation.

Step 2: Locate the failure site

semantic_search_nodes(query="<error message fragment or function name>")

Find the exact node. Note its file path and line.

Step 3: Check recent changes

detect_changes()

Most bugs are introduced by recent changes. High-risk score on a recently changed function near the failure site = strong lead.

Step 4: Trace the call chain

query_graph(node_id="...", pattern="callers_of")   // who triggered this
query_graph(node_id="...", pattern="callees_of")   // what it delegates to

Trace up until you find where bad data originates. Fix at source, not at symptom.

Step 5: Check affected flows

get_affected_flows(changed_nodes=[...])

Confirms which execution path passes through the broken function. Helps rule out unrelated code.

Step 6: Read the source only for the failing node

get_review_context(node_ids=["<failing_node_id>"])

Don't read entire files. One node at a time until root cause is clear.

Tundra-Specific Debugging Map

Symptom	Where to look first
401 on valid session	tundrad-auth session extractor, cookie name
403 unexpected	RBAC scope check in handler, authz_matrix.rs test coverage
500 from API handler	unwrap() on None, missing ? propagation
Rust compile error in tundrad-api	Check routes/mod.rs pub declaration + lib.rs route registration
Panel route blank / crashes	routeTree.gen.ts type map mismatch; check FileRoutesByFullPath
TanStack Query stuck loading	queryFn fetch URL typo, refetchInterval returning wrong value
Migration fails	NOT NULL without DEFAULT, or type mismatch on existing rows
Encrypted field panics	Wrong EncryptedField<T> type parameter, or master key format
WP provisioning stuck	State never updated to active/error — check tokio::spawn task panicked silently
Docker: sqlx: not found	/cargo/bin not in PATH; check docker-compose.override.yml

Red Flags — Stop and Investigate Deeper

• You've tried 2 different fixes and neither worked → wrong root cause, re-read call chain
• Fix requires changing 5+ files → you're patching a symptom, not a cause
• Error message mentions a type you don't recognize → read the type definition first
• "It works locally but not in Docker" → env var, volume mount, or PATH difference
• Test passes in isolation but fails in suite → shared state / missing test isolation

After Finding Root Cause

Only then: write a minimal failing test (per superpowers:test-driven-development), then fix.