debug

---

name: debug description: Debug workflow per foundation command. triggers:

• debug
• /debug

---

Debug Command

Purpose

Check for pending error reports and debug/resolve them. Supports cross-repo error queue checking for sibling repositories. Also manages the error debugging automation watcher.

Command Usage

/debug [action|target-repo-name]

Modes of Operation:

The command operates in two modes based on the first argument:

1. Watcher Management Mode

If the first argument is a watcher management action (start, stop, status, logs, restart), manage the error debugging automation watcher:

/debug start      # Start the error debugging watcher
/debug stop       # Stop the running watcher
/debug status     # Check watcher status
/debug logs       # Show watcher logs
/debug restart    # Restart the watcher

2. Error Debugging Mode (Default)

If the first argument is not a watcher action (or no arguments provided), check and debug pending errors:

/debug                    # Check current repo's pending errors (default)
/debug neotoma            # Check sibling repo's pending errors
/debug personal-project   # Check another sibling repo

Note: To check watcher status, use /debug status. The default behavior (no arguments) checks for pending errors in the current repository.

Parameters:

• action (optional): Watcher management action (start, stop, status, logs, restart)
  • If provided, manages the error debugging automation watcher
  • If omitted: Defaults to error debugging mode (check pending errors)
• target-repo-name (optional): Name of sibling repository to check for pending errors
  • Must be a sibling repository (shares same parent directory)
  • Only used if first argument is not a watcher action

Examples:

# Watcher management
/debug start      # Start watcher
/debug status     # Check watcher status
/debug logs        # View watcher logs
/debug stop        # Stop watcher

# Error debugging
/debug                    # Check current repo's pending errors
/debug neotoma            # Check sibling repo's pending errors
/debug --list-only       # List errors without debugging
/debug --all --auto      # Process all errors automatically

Workflow

Mode Detection

1. Check First Argument:
   • If first argument is start, stop, status, logs, or restart:
     • Enter Watcher Management Mode (see section below)
     • Execute the watcher management action and exit
   • Otherwise (including no arguments):
     • Enter Error Debugging Mode (continue with Target Repository Resolution)

Watcher Management Mode

Action: start

1. Check if already running:

   • Check for PID file: .cursor/error_reports/watcher.pid
   • If PID file exists, verify process is still running
   • If running, exit with message: "Error debugging watcher is already running (PID: {pid})"

2. Verify configuration:

   • Load foundation-config.yaml
   • Check development.error_debugging.enabled === true
   • If disabled, exit with error

3. Create necessary directories:

   • Ensure .cursor/error_reports/ exists
   • Ensure log directory exists (if configured)

4. Start watcher in background:

   • Run: node scripts/trigger_error_debug_cli.js --watch > .cursor/error_reports/watcher.log 2>&1 &
   • Capture PID of background process
   • Write PID to .cursor/error_reports/watcher.pid
   • Output: "Started error debugging watcher (PID: {pid})"

5. Verify start:

   • Wait 1 second
   • Check if process is still running
   • If not running, read log file and show error

Action: stop

1. Check if running:

   • Read PID from .cursor/error_reports/watcher.pid
   • If PID file doesn't exist, exit: "Error debugging watcher is not running"

2. Verify process exists:

   • Check if process with PID is running
   • If not running, remove stale PID file and exit: "Watcher process not found (stale PID file removed)"

3. Stop process:

   • Send TERM signal to process
   • Wait up to 5 seconds for graceful shutdown
   • If still running, send KILL signal
   • Remove PID file
   • Output: "Stopped error debugging watcher (PID: {pid})"

Action: status (default)

1. Check PID file:

   • Read .cursor/error_reports/watcher.pid
   • If not found: "Status: Not running"

2. Check if process is running:

   • Verify process with PID exists
   • If not: "Status: Not running (stale PID file)"
   • Remove stale PID file

3. If running, show:

   • PID
   • Uptime (how long it's been running)
   • Configuration status (enabled/disabled)
   • Last log entry (if log file exists)

4. Also show pending errors count:

   • Read .cursor/error_reports/pending.json
   • Display count of pending errors
   • If errors exist, suggest running /debug to debug

Action: logs

1. Check log file:

   • Read .cursor/error_reports/watcher.log
   • If not found: "No log file found. Watcher may not have started yet."

2. Display logs:

   • Show last 50 lines (configurable)
   • Or tail logs if --follow flag provided

Action: restart

1. Run stop action (if running)
2. Wait 1 second
3. Run start action

Implementation Notes for Watcher Management:

• PID File: .cursor/error_reports/watcher.pid
• Log File: .cursor/error_reports/watcher.log
• Process Verification: Use ps -p $PID (macOS/Linux) or platform-specific commands
• Graceful Shutdown: TERM signal with 5s timeout, then KILL if needed

Error Debugging Mode

1. Target Repository Resolution

1. Get Current Repository Path:

   git rev-parse --show-toplevel
   

   Store as current_repo_path

2. Resolve Target Repository Path:

   • If target-repo-name provided:
     • Sanitize repo name (same rules as report: alphanumeric, hyphens, underscores, dots only)
     • Get parent directory: dirname(current_repo_path)
     • Construct target path: parent_dir/target-repo-name
   • If omitted:
     • Use current_repo_path (check current repo)

3. Validate Target Repository:

   • Path exists and is a directory
   • Contains .git directory (is git repo)
   • Has .cursor/error_reports/ directory
   • Has pending.json file (if not, no pending errors)

2. Load Pending Errors

1. Read Pending Queue:

   const pendingPath = path.join(targetRepoPath, '.cursor', 'error_reports', 'pending.json');
   
   if (!fs.existsSync(pendingPath)) {
     console.log(`No pending errors found in ${targetRepoName}.`);
     return;
   }
   
   const pending = JSON.parse(fs.readFileSync(pendingPath, 'utf8'));
   
   if (pending.length === 0) {
     console.log(`No pending errors found in ${targetRepoName}. All clear!`);
     return;
   }
   

2. Sort by Priority:

   const severityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
   
   pending.sort((a, b) => {
     // Sort by severity first
     const severityDiff = severityOrder[a.severity] - severityOrder[b.severity];
     if (severityDiff !== 0) return severityDiff;
   
     // Then by timestamp (oldest first)
     return new Date(a.timestamp) - new Date(b.timestamp);
   });
   

3. Display Pending Errors:

   Found {count} pending error(s) in {target_repo_name}:
   
   1. [CRITICAL] Build Error (error_20250131_143022_build.json)
      - ID: 01JQZ8X9K2M3N4P5Q6R7S8T9U0
      - Timestamp: 2025-01-31T14:30:22Z
      - Message: Cannot find module '../db'
   
   2. [HIGH] Runtime Error (error_20250131_144510_runtime.json)
      - ID: 01JQZ8X9K2M3N4P5Q6R7S8T9U1
      - Timestamp: 2025-01-31T14:45:10Z
      - Message: MCP error -32603: UNKNOWN_CAPABILITY
   

3. Select Error to Debug

Default Behavior: Auto-select highest priority

1. Select First Error:

   • Highest severity (critical > high > medium > low)
   • Oldest timestamp within same severity

2. Prompt User for Confirmation:

   Debugging highest priority error:
   
   Error ID: 01JQZ8X9K2M3N4P5Q6R7S8T9U0
   Category: build
   Severity: critical
   Message: Cannot find module '../db'
   Affected files: src/services/raw_storage.ts
   
   Proceed with debugging? (yes/no/choose-different/list-only)
   
   - yes: Debug this error
   - no: Skip debugging
   - choose-different: Select a different error from the list
   - list-only: Display errors without debugging
   

3. Handle User Response:

   • yes: Proceed to step 4
   • no: Exit without debugging
   • choose-different: Display numbered list, prompt for selection
   • list-only: Display all errors and exit (same as --list-only flag)

4. Load Error Details

1. Read Full Error Report:

   const errorJsonPath = pending[selectedIndex].file_path;
   const errorReport = JSON.parse(fs.readFileSync(errorJsonPath, 'utf8'));
   

2. Display Error Details:

   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   Error Report Details
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   
   Error ID: 01JQZ8X9K2M3N4P5Q6R7S8T9U0
   Category: build
   Severity: critical
   Timestamp: 2025-01-31T14:30:22Z
   
   Error Message:
   Cannot find module '../db'
   
   Stack Trace:
   Error: Cannot find module '../db'
     at Object.<anonymous> (src/services/raw_storage.ts:1:1)
     at Module._compile (node:internal/modules/cjs/loader:1376:14)
     ...
   
   Affected Files:
   - src/services/raw_storage.ts
   - src/services/interpretation.ts
   - src/services/entity_queries.ts
   
   Affected Modules:
   - db
   
   Original Task:
   Transfer contacts from Parquet to Neotoma
   
   Source Repository:
   personal-project (/Users/user/Projects/personal-project)
   
   Target Repository:
   neotoma (/Users/user/Projects/neotoma)
   
   Environment:
   - Node: v20.11.0
   - OS: darwin
   - Environment: development
   
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   

5. Debug & Fix Error

Integration with fix_feature_bug Command:

1. Prepare Context for Bug Fix:

   • Error message and stack trace
   • Affected files list
   • Affected modules list
   • Original task description

2. Trigger Bug Fix Workflow:

   • If development.error_debugging.integrate_fix_feature_bug: true:
     • Call fix_feature_bug command with error context
     • Pass affected files and error details
   • If integration disabled:
     • Present error details and let user fix manually

3. Follow Standard Bug Fix Process:

   • Load relevant documents (specs, subsystems)
   • Classify bug (if error classification configured)
   • Apply correction rules
   • Add regression test
   • Run tests
   • Verify fix resolves the error

4. Alternative: Manual Debugging Mode:

   • If user selects manual mode:
     • Display error details
     • Open affected files in editor
     • User investigates and fixes manually
     • User indicates when fix is complete

6. Update Resolution Status

After successful fix:

1. Update Error Report:

   errorReport.resolution_status = 'resolved';
   errorReport.resolution_notes = 'Fixed by correcting import path in raw_storage.ts';
   errorReport.resolved_at = new Date().toISOString();
   errorReport.resolved_by = 'cursor-agent';
   
   fs.writeFileSync(errorJsonPath, JSON.stringify(errorReport, null, 2), 'utf8');
   

2. Move to Resolved Directory:

   const resolvedDir = path.join(targetRepoPath, '.cursor', 'error_reports', 'resolved');
   fs.mkdirSync(resolvedDir, { recursive: true });
   
   const jsonBasename = path.basename(errorJsonPath);
   const mdBasename = jsonBasename.replace('.json', '.md');
   
   const resolvedJsonPath = path.join(resolvedDir, jsonBasename);
   const resolvedMdPath = path.join(resolvedDir, mdBasename);
   
   const errorMdPath = errorJsonPath.replace('.json', '.md');
   
   fs.renameSync(errorJsonPath, resolvedJsonPath);
   if (fs.existsSync(errorMdPath)) {
     fs.renameSync(errorMdPath, resolvedMdPath);
   }
   

3. Remove from Pending Queue:

   const pending = JSON.parse(fs.readFileSync(pendingPath, 'utf8'));
   const filtered = pending.filter(e => e.error_id !== errorReport.error_id);
   fs.writeFileSync(pendingPath, JSON.stringify(filtered, null, 2), 'utf8');
   

4. Update Markdown Summary:

   • Append resolution notes to markdown file
   • Add resolved timestamp
   • Move to resolved directory

If fix fails:

1. Update Status to Failed:

   errorReport.resolution_status = 'failed';
   errorReport.resolution_notes = 'Fix attempted but tests still failing. Requires manual investigation.';
   errorReport.failed_at = new Date().toISOString();
   
   fs.writeFileSync(errorJsonPath, JSON.stringify(errorReport, null, 2), 'utf8');
   

2. Keep in Pending Queue:

   • Do not move to resolved
   • Update error report with failure notes
   • User can retry later

7. Output Summary

On Successful Resolution:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Error Resolved Successfully
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Error ID: 01JQZ8X9K2M3N4P5Q6R7S8T9U0
Category: build
Severity: critical

Resolution:
Fixed by correcting import path in raw_storage.ts

Files Changed:
- src/services/raw_storage.ts

Tests Added:
- tests/integration/import_resolution.test.ts

Archived to:
- {target_repo}/.cursor/error_reports/resolved/error_20250131_143022_build.json
- {target_repo}/.cursor/error_reports/resolved/error_20250131_143022_build.md

Remaining pending errors: 1
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Scenario 6: Watcher Management

# Check watcher status (default)
/debug
/debug status

# Start watcher
/debug start

# View logs
/debug logs

# Stop watcher
/debug stop

# Restart watcher
/debug restart

Output (status):

Error Debugging Watcher Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Status: Running
PID: 12345
Uptime: 2h 15m 30s
Configuration: Enabled

Pending Errors: 2
Last Activity: 2025-01-31T15:30:00Z

Use /debug to debug pending errors.

On Failed Resolution:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Error Resolution Failed
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Error ID: 01JQZ8X9K2M3N4P5Q6R7S8T9U0
Category: build
Severity: critical

Status: Failed
Notes: Fix attempted but tests still failing. Requires manual investigation.

Error remains in pending queue for retry.

Remaining pending errors: 2
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Command Flags

--list-only

Display pending errors without debugging:

/debug --list-only
/debug neotoma --list-only

Behavior:

• Display all pending errors
• Do not prompt for debugging
• Exit after displaying list

--all

Process all pending errors in priority order:

/debug --all
/debug neotoma --all

Behavior:

• Process each error in priority order
• Prompt for confirmation before each error (unless --auto also specified)
• Continue until all errors processed or user cancels

--auto

Skip confirmation prompts:

/debug --auto
/debug neotoma --auto

Behavior:

• Auto-debug highest priority error without confirmation
• Useful for automated Cloud Agent processing

Combined Flags

/debug neotoma --all --auto

Process all pending errors in neotoma repo without prompts

Error Handling

Validation Failures

No Error Reports Directory:

No error reports found in {target_repo}.

Directory .cursor/error_reports/ does not exist.
Use /report to create error reports.

Empty Pending Queue:

No pending errors found in {target_repo}.

All clear!

Invalid Target Repo:

Error: Target repository not found: /Users/user/Projects/non-existent-repo

Check repo name and try again.

Invalid Repo Name (Path Traversal):

Error: Invalid repo name: ../secret-repo. Only alphanumeric, hyphens, underscores, and dots allowed.

Permission Error:

Error: No write permission for target repository: /Users/user/Projects/neotoma

Cannot update error reports. Check file permissions.

Configuration

Add to foundation-config.yaml:

development:
  error_debugging:
    enabled: true
    auto_select_highest_priority: true
    require_confirmation: true  # Prompt before debugging
    integrate_fix_feature_bug: true  # Use fix_feature_bug for resolution
    max_errors_to_display: 10
    auto_archive_resolved: true  # Move resolved errors to archive
    automation:
      watch_mode: true  # Enable continuous monitoring via watcher
      cursor_cli:
        # ... cursor_cli configuration ...

Watcher Management:

• When watch_mode: true, the watcher automatically monitors for new errors
• Use /debug start to start the watcher
• Use /debug status to check watcher and pending errors
• Watcher logs are written to .cursor/error_reports/watcher.log

Integration Points

With report Command

• Reads error reports created by report
• Processes the pending queue created by report
• Updates resolution status
• Moves resolved errors to archive

With fix_feature_bug Command

• Automatically triggers fix_feature_bug for each error
• Passes error context (message, stack trace, affected files)
• Captures fix results and updates error report
• Updates resolution_status based on fix success/failure

With Cursor Cloud Agent

• Can be used by Cloud Agent to process error queue automatically
• Updates resolution status as Cloud Agent works
• Provides structured feedback on resolution progress
• Moves resolved errors to archive for audit trail

Example Usage Scenarios

Scenario 1: Check & Debug Current Repo

/debug

Output:

Found 2 pending error(s) in neotoma:

1. [CRITICAL] Build Error (error_20250131_143022_build.json)
   - ID: 01JQZ8X9K2M3N4P5Q6R7S8T9U0
   - Timestamp: 2025-01-31T14:30:22Z
   - Message: Cannot find module '../db'

2. [HIGH] Runtime Error (error_20250131_144510_runtime.json)
   - ID: 01JQZ8X9K2M3N4P5Q6R7S8T9U1
   - Timestamp: 2025-01-31T14:45:10Z
   - Message: MCP error -32603: UNKNOWN_CAPABILITY

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Debugging highest priority error (CRITICAL):

Error ID: 01JQZ8X9K2M3N4P5Q6R7S8T9U0
Category: build
Severity: critical
Message: Cannot find module '../db'

Affected files:
- src/services/raw_storage.ts
- src/services/interpretation.ts
- src/services/entity_queries.ts

Proceed with debugging? (yes/no/choose-different/list-only)

Scenario 2: Check Sibling Repo

/debug neotoma

Output:

Checking pending errors in: /Users/user/Projects/neotoma

Found 1 pending error(s) in neotoma:

1. [HIGH] Runtime Error (error_20250131_144510_runtime.json)
   - ID: 01JQZ8X9K2M3N4P5Q6R7S8T9U1
   - Timestamp: 2025-01-31T14:45:10Z
   - Message: Storage bucket not found
   - Source: personal-project

Debugging error...

[Proceeds with debugging workflow]

Scenario 3: List Only Mode

/debug --list-only

Output:

Found 2 pending error(s) in neotoma:

1. [CRITICAL] Build Error (2025-01-31T14:30:22Z)
   - ID: 01JQZ8X9K2M3N4P5Q6R7S8T9U0
   - Message: Cannot find module '../db'
   - Affected: src/services/raw_storage.ts

2. [HIGH] Runtime Error (2025-01-31T14:45:10Z)
   - ID: 01JQZ8X9K2M3N4P5Q6R7S8T9U1
   - Message: MCP error -32603: UNKNOWN_CAPABILITY
   - Affected: src/server.ts

Use /debug to debug highest priority error.

Scenario 4: No Pending Errors

/debug

Output (if no watcher action specified, shows status):

Error Debugging Watcher Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Status: Running
PID: 12345
Uptime: 2h 15m 30s

Pending Errors: 0

All clear! No pending errors to debug.

Or if checking errors directly:

No pending errors found in current repository.

All clear!

Scenario 5: Debug All Errors

/debug --all

Output:

Found 3 pending error(s). Processing all in priority order...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Processing error 1 of 3: [CRITICAL] Build Error
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[Debugging workflow for error 1]

[After error 1 resolved]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Processing error 2 of 3: [HIGH] Runtime Error
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[Debugging workflow for error 2]

...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
All Errors Processed
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Total errors: 3
Resolved: 2
Failed: 1

Remaining pending errors: 1

Implementation Checklist

Mode Detection

• Check first argument for watcher action (start, stop, status, logs, restart)
• Route to Watcher Management Mode if action detected
• Route to Error Debugging Mode otherwise

Watcher Management Mode

• Handle start action (check if running, verify config, start watcher, verify)
• Handle stop action (read PID, verify process, graceful shutdown, cleanup)
• Handle status action (check PID, verify process, show status + pending errors)
• Handle logs action (read log file, display last N lines or tail)
• Handle restart action (stop then start)
• Manage PID file (create on start, remove on stop, cleanup stale)
• Manage log file (write to watcher.log, handle rotation)

Error Debugging Mode

• Parse target-repo-name parameter (if provided)
• Sanitize repo name (prevent path traversal)
• Resolve target repository path
• Validate target repository exists and is git repo
• Check for .cursor/error_reports/ directory
• Read pending.json queue
• Sort errors by priority (severity + timestamp)
• Display pending errors to user
• Select error to debug (highest priority or user choice)
• Prompt user for confirmation (unless --auto flag)
• Load full error report details
• Display error context to user
• Trigger fix_feature_bug with error context (or manual mode)
• Update resolution_status in error report
• Move resolved error to archive
• Remove from pending queue
• Output resolution summary
• Handle --list-only flag (display without debugging)
• Handle --all flag (process all errors)
• Handle --auto flag (skip confirmation)

Repository Metadata Collection

For each error report, collect repository metadata:

function getRepositoryMetadata(repoPath) {
  const name = path.basename(repoPath);

  let remoteUrl = null;
  try {
    remoteUrl = execSync('git remote get-url origin', { cwd: repoPath })
      .toString()
      .trim();
  } catch {
    // No remote or error getting remote
  }

  return {
    path: repoPath,
    name: name,
    remote_url: remoteUrl
  };
}

Testing Scenarios

Test 1: Debug Current Repo with Pending Errors

Setup: Create sample pending.json with 2 errors Expected: Display errors, debug highest priority

Test 2: Debug Sibling Repo with Pending Errors

Setup: Create errors in sibling repo Expected: Display errors from sibling repo, debug highest priority

Test 3: No Pending Errors

Setup: Empty or missing pending.json Expected: Message "No pending errors found. All clear!"

Test 4: Missing Error Reports Directory

Setup: Target repo without .cursor/error_reports/ Expected: Error message with instruction to use /report

Test 5: Invalid Target Repo Name

Setup: Use non-existent sibling repo name Expected: Error message about target repo not found

Test 6: List Only Mode

Setup: Pending errors exist Expected: Display errors without debugging, exit

Test 7: Debug All Mode

Setup: Multiple pending errors Expected: Process all errors in priority order