/debugging

name: debugging
description: Structured debugging session with team knowledge capture
category: Development Tools
version: 0.4.4

Debugging Command

Fast, systematic debugging with hypothesis testing and team knowledge capture, with optional worktree isolation.

Purpose

Transform chaotic debugging into efficient investigation with:

• Quick triage and pattern recognition
• Known issues search before reinventing solutions
• Hypothesis-driven testing
• Team knowledge documentation

**NEW in v0.4.4**: Automatic context detection - run from Main OR from worktree directly! **v0.4.3**: Support for worktree isolation with `--worktree` flag for debugging sessions requiring code modifications.

Context Detection (Auto)

The `/debugging` command **automatically detects** where you run it from:

From Main Repository

# Working directory: ~/Documents/watchora
$ /debugging "Check API timeout"
→ Behavior: Read-only investigation on Main (default)
→ Optional: Add --worktree for code modifications

From Debug Worktree

# Working directory: ~/Documents/watchora/worktrees/debug
$ /debugging "Check API timeout"
→ Behavior: Automatically uses worktree (no --worktree needed!)
→ Syncs, locks, creates branch, works in current directory

**Key Point**: If you have a dedicated Cursor window open on `worktrees/debug/`, you can use `/debugging` directly from there!

Usage

# From Main: Investigate on Main (read-only, quick)
/debugging "Check why API returns 500"

# From Main: With worktree isolation (modifications needed)
/debugging "Memory leak in WebSocket handler" --worktree

# From Worktree: Auto-detects worktree context
cd worktrees/debug/
/debugging "Memory leak issue"  # Automatically uses worktree!

# Manage active session (works from anywhere)
/debugging --resolve          # Complete and document
/debugging --abort            # Cancel session
/debugging --status           # Show current status
/debugging --pause            # Pause session
/debugging --resume           # Resume paused session

# Migrate from Main to worktree
/debugging --to-worktree      # Move current session to worktree

# List past sessions
/debugging --list             # Show all debug sessions

Options

| Option | Description | |--------|-------------| | `--worktree` | Use debug worktree for isolation | | `--to-worktree` | Migrate current session from Main to worktree | | `--resolve` | Resolve session (document + cleanup) | | `--abort` | Abort session without documenting | | `--status` | Show current session status | | `--pause` | Pause session and save state | | `--resume` | Resume paused session | | `--list` | List all past debug sessions |

Workflow

1. Quick Triage (30 seconds)

**Assess immediately**:

• Symptom description
• Environment (production/staging/dev/all)
• Severity (revenue impact, user impact, scope)
• Initial observations

**Auto-detect red flags**:

• "production only" → env/config difference
• "after deployment" → migration/change issue
• "intermittent" → race condition/timing
• "specific users" → data/permission issue

2. Known Issues Check (2 min)

**Web search** for existing solutions:

• Error message + library/framework name
• GitHub issues in relevant repos
• Stack Overflow matches
• Release notes if recent upgrade

**If found**: Link solution, adapt, skip investigation.

3. Quick Wins (5 min)

Test obvious fixes before deep dive:

• Restart service/clear cache
• Check recent changes (git log)
• Verify environment variables
• Check dependency versions
• Review recent deployments

Workflow: Default (Main)

Step 1: Start Investigation on Main

$ /debugging "OAuth timeout in production"

🔍 Debugging on Main (read-only investigation)

📝 Session: .prds/debug-sessions/2025-01-13-oauth-timeout-production.md

💡 On Main - for read-only investigation
   Use --worktree if you need to make changes

Step 2: Investigation

• Read code
• Check logs
• Analyze stack traces
• Form hypotheses
• No modifications (read-only)

Step 3: Resolve

$ /debugging --resolve

💬 Resolution status?
1. Resolved with fix → Create PR (requires worktree)
2. Resolved without fix (config/data issue) → Document only
3. Workaround → Document + TODO
4. Not resolved → Save state for later

Choose: 2

# If option 2 (no fix needed):
✅ Documented in .prds/debug-sessions/2025-01-13-oauth-timeout-production.md

Root cause: Redis session TTL too short in production config
Solution: Updated production config (no code changes)

Session closed.

Workflow: With Worktree (from Main)

Step 1: Start Session in Worktree

$ /debugging "Memory leak in WebSocket handler" --worktree

🔍 Checking worktree debug/...

# AUTO-SYNC (Intelligent)
🔄 Syncing worktree (5 commits behind)...

Recent changes:
  - a3f2c1d fix: WebSocket cleanup
  - 8d4e2a9 feat: Connection pooling
  - 1c8f3b2 refactor: Event handlers

✅ Synced with main

# START SESSION
✅ Started in worktrees/debug/
📝 Branch: debug/memory-leak-websocket
📄 Session: .prds/debug-sessions/2025-01-13-memory-leak-websocket.md
🔒 Locked worktree (one session at a time)

💻 Open in new window: code worktrees/debug/

**Auto-sync thresholds** (same as /ship):

• 0 commits: ✅ No sync needed
• 1-10 commits: 🔄 Silent auto-sync
• 10-50 commits: ⚠️ Propose sync with preview
• 50+ commits: ❌ Force sync (required)

Step 2: Investigation with Modifications

Work in `worktrees/debug/`:

• Reproduce bug
• Test hypotheses
• Add debug logging
• Experimental fixes
• Complete isolation

Step 3: Resolve with Fix

$ /debugging --resolve

💬 Resolution status?
1. Resolved with fix → Create PR
2. Resolved without fix → Document only
3. Workaround → Document + TODO
4. Not resolved → Save state

Choose: 1

# Fix found - create PR
✅ Committed fix
📤 PR #236: fix: Memory leak in WebSocket close handler
📝 Updated session doc:
   Root cause: Event listeners not cleaned up
   Solution: Added cle