---

name: debugging description: Systematic debugging approach emphasizing temporal awareness, narrow scope, and appropriate investigation strategies. Use when investigating bugs, analyzing failures, or troubleshooting issues.

Debugging

State Assumptions First

Before investigating, explicitly state:

• Environment - Local? Staging? Production? Which instance?
• Time context - When did issue occur? What time range matters?
• Current time - Query frequently to maintain temporal awareness
• Expected behavior - What should happen?

Temporal Awareness (CRITICAL)

Time moves during debugging. Agents lack inherent time sense - develop it:

• Query current time frequently - Not just for ranges, but to stay oriented
• Data goes stale - What you checked 10 minutes ago may have changed
• Systems evolve - Services restart, data updates, state shifts
• Be explicit about "when" - "As of [time], the state was..."
• Understand operations take time - Nothing is instant

This makes you a better collaborator and keeps investigations grounded.

Investigation Approach

When Reproducible

1. Reproduce reliably - Create minimal reproduction case
2. Write failing test - Capture the bug (follows good development workflow)
3. Isolate - Binary search, remove variables
4. Fix - Make test pass
5. Verify - Confirm fix, check for regressions

When Not Reproducible (Production, Intermittent)

1. Pin down symptom - Falsifiable statement of what's wrong
2. Identify source of truth - Logs? Database? Metrics? Where's reliable data?
3. Narrow scope - Smallest time range, fewest services, minimal data
4. Compare - Expected vs observed behavior
5. Expand cautiously - Only when narrow investigation exhausted

Core Principles

Scope Management:

• Start narrow, expand only when stuck
• Prefer precise queries over broad sweeps
• One variable at a time

Safety:

• Default to read-only operations
• For writes/deletes: show exact operation, ask explicit approval
• State impact before executing

Tooling:

• Prefer MCP servers when available
• Use project-specific debugging tools (debuggers, profilers, tracers)
• Apply project knowledge to choose appropriate tools

Common Investigation Patterns

"Nothing is happening" → Check errors, logs, connectivity "Wrong data" → Verify environment, input sources, transformations
"Intermittent" → Tighten time window, look for patterns, check resource constraints "Used to work" → Identify what changed (code, config, data, environment)