report-error

---

name: report-error description: Report error per foundation command. triggers:

• report error
• /report_error
• report-error

---

Report Error Command

Purpose

Enable agents to report errors for automated resolution by Cursor Cloud Agent. This command detects, classifies, and documents errors in a structured format for systematic resolution.

Supports cross-repo reporting: Report errors to sibling repositories (repos sharing the same parent directory) by passing the target repo name.

Command Usage

/report_error [target-repo-name] [--no-wait] [--timeout SECONDS] [--poll-interval SECONDS]

Parameters:

• target-repo-name (optional): Name of sibling repository to report error to
  • Must be a sibling repository (shares same parent directory)
  • Example: If current repo is /Users/user/Projects/personal, target neotoma resolves to /Users/user/Projects/neotoma
  • If omitted: Auto-detect target repository based on error origin (see Auto-Detection below)
• --no-wait (optional): Disable wait-for-resolution mode (default: wait mode is enabled)
• --timeout SECONDS (optional): Maximum time to wait for resolution (default: 300 seconds / 5 minutes)
• --poll-interval SECONDS (optional): How often to check error status (default: 5 seconds)

Default Behavior:

• Wait mode is enabled by default - Agent will monitor error status until resolved or timeout
• Auto-detection is enabled - If target-repo-name is not provided, automatically detect target repository based on error origin

Examples:

# Auto-detect target repo and wait for resolution (default behavior)
/report_error

# Explicitly specify target repo (auto-detection disabled)
/report_error neotoma

# Disable wait mode (report and continue immediately)
/report_error --no-wait

# Custom timeout (10 minutes, default is 5 minutes)
/report_error --timeout 600

# Custom poll interval (check every 2 seconds, default is 5 seconds)
/report_error --poll-interval 2

# Explicit target repo with custom timeout
/report_error neotoma --timeout 600

When to Use

Use this command when you encounter:

• Build errors (TypeScript compilation, module resolution)
• Runtime errors (MCP server errors, API failures, database errors)
• Test failures
• Dependency issues (missing modules, version conflicts)
• Configuration errors (missing env vars, invalid config)

Auto-Detection: The command automatically detects the target repository when errors originate from MCP servers or external modules. For example:

• Errors from mcp_neotoma_* functions → automatically report to neotoma repo
• Errors from mcp_asana_* functions → automatically report to asana repo (if exists)
• Errors with file paths containing /Projects/neotoma/ → automatically report to neotoma repo

Workflow

1. Target Repository Resolution

1. Get Current Repository Path:

   git rev-parse --show-toplevel
   

   Store as current_repo_path

2. Auto-Detect Target Repository (if target-repo-name not provided):

   Analyze error context to determine target repository:

   MCP Error Detection:

   • If error message contains MCP error or mcp_ prefix:
     • Extract MCP server name from error context
     • Check agent_context.command for MCP function names (e.g., mcp_neotoma_ingest_structured)
     • Map MCP server to target repository using configured mapping or default patterns:
       • mcp_neotoma → neotoma
       • mcp_asana → asana (if exists)
       • mcp_gmail → gmail (if exists)
       • mcp_google-calendar or mcp_google_calendar → google-calendar (if exists)
       • Pattern: mcp_<server-name> → lookup in mcp_server_mapping config or use <server-name>
     • Validate target repository exists before using

   Module Path Detection:

   • If error contains file paths:
     • Extract repository name from path patterns:
       • /Users/user/Projects/neotoma/ → neotoma
       • /Users/user/Projects/foundation/ → foundation
     • Check if path matches sibling repository structure

   Error Source Detection:

   • If error originates from MCP call:
     • Check agent_context.command for MCP function names
     • Extract server name from command (e.g., mcp_neotoma_ingest_structured → neotoma)

   Fallback:

   • If auto-detection fails or no match found:
     • Use current_repo_path (local reporting)
     • Log warning: "Could not auto-detect target repository, using current repo"

3. Resolve Target Repository Path:

   • If target-repo-name parameter provided:
     • Use explicit target (skip auto-detection)
     • Get parent directory: dirname(current_repo_path)
     • Construct target path: parent_dir/target-repo-name
     • Example: Current repo at /Users/user/Projects/personal, target neotoma → /Users/user/Projects/neotoma
   • If parameter omitted and auto-detection succeeded:
     • Use auto-detected target repository
   • If parameter omitted and auto-detection failed:
     • Use current_repo_path (local reporting)

4. Sanitize Repository Name (if provided or auto-detected):

   • Ensure repo name doesn't contain path traversal characters (.., /, \)
   • Validate repo name is a valid directory name (alphanumeric, hyphens, underscores, dots)
   • Abort if repo name contains invalid characters

5. Validate Target Repository:

   • Verify target path exists and is a directory
   • Verify target contains .git directory (is a git repository)
   • Verify write permissions to target directory
   • If validation fails: abort with clear error message

2. Error Detection & Collection

Extract the following from context:

• Error message and stack trace
• Affected files/modules from error paths
• Agent context (agent_id, task being performed, command name)
• Environment details (Node version, OS, etc.)
• MCP context: Function names, server identifiers, module paths

For Auto-Detection:

• Extract MCP server name from error message (e.g., "MCP error" from mcp_neotoma)
• Extract command name from agent context (e.g., mcp_neotoma_ingest_structured)
• Extract repository paths from stack traces and affected files
• Map detected sources to sibling repository names

3. Error Classification

Classify error into one of these categories:

• build: TypeScript compilation, module resolution, missing dependencies
• runtime: MCP server errors, API failures, database errors
• test: Test failures, assertion errors
• dependency: Missing modules, version conflicts
• configuration: Missing env vars, invalid config

4. Severity Assessment

Assign severity based on impact:

• critical: Server crashes, data loss, security issues
• high: Feature breakage, blocking errors
• medium: Non-blocking errors, warnings
• low: Cosmetic issues, deprecation warnings

5. Generate Error Report

Create a structured error report with:

• Error ID (UUIDv7 or timestamp-based)
• Timestamp (ISO 8601)
• Category and severity
• Sanitized error message (no PII)
• Truncated stack trace (max 5000 chars)
• Affected files and modules
• Agent context
• Environment details
• Repository metadata (source_repo, target_repo)
• Resolution status (initially "pending")

6. Store Error Report in Target Repository

1. Ensure Target Directory Structure:

   • Create target_repo/.cursor/error_reports/ if missing
   • Create target_repo/.cursor/error_reports/pending/ if missing
   • Create target_repo/.cursor/error_reports/resolved/ if missing

2. Write Error Report Files:

   • Save JSON: target_repo/.cursor/error_reports/pending/error_[timestamp]_[category].json
   • Save Markdown: target_repo/.cursor/error_reports/pending/error_[timestamp]_[category].md

3. Update Pending Queue:

   • Append to target_repo/.cursor/error_reports/pending.json
   • Include priority/severity for processing order
   • File paths in pending.json should reference the pending/ subdirectory

7. Output Summary

Present to user:

• Error ID and category
• Severity level
• Target repository path (indicate if auto-detected)
• Location of report files
• Queue status

8. Wait-for-Resolution (Default Behavior)

IMPORTANT: Wait mode is enabled by default unless --no-wait is specified.

After creating error report, monitor resolution status:

1. Check Wait Mode:

   • If --no-wait flag provided: Skip wait mode, exit immediately
   • Otherwise: Proceed with wait mode

2. Monitor Resolution:

   • Poll error report file for status changes
   • Critical: Check both pending/ and resolved/ directories on each poll
     • Files are moved from pending/ to resolved/ by Cursor Cloud Agent upon resolution
     • If file not found in pending/, check resolved/ before assuming file is missing
   • Check resolution_status field in JSON report
   • Status values: pending → in_progress → resolved | failed
   • Use configured timeout and poll interval

3. Resolution Detection:

   • Resolved: Status changes to "resolved"
     • Output resolution notes
     • Exit with success
   • Failed: Status changes to "failed"
     • Output failure reason
     • Exit with error
   • Timeout: Timeout reached while status is pending or in_progress
     • Output current status
     • Exit with warning (non-fatal)

4. Resume/Retry Logic:

   • After resolution, agent can:
     • Retry: Re-execute the operation that failed
     • Skip: If error indicates operation should be skipped
     • Continue: Proceed with next operation

Error Report Schema

{
  "error_id": "uuid-v7",
  "timestamp": "ISO-8601",
  "category": "build|runtime|test|dependency|configuration",
  "severity": "critical|high|medium|low",
  "error_message": "sanitized error message",
  "stack_trace": "truncated stack trace",
  "affected_files": ["path/to/file1.ts", "path/to/file2.ts"],
  "affected_modules": ["module_name"],
  "agent_context": {
    "agent_id": "cursor-agent",
    "task": "description of task",
    "command": "command_name if applicable"
  },
  "repositories": {
    "source_repo": {
      "path": "/absolute/path/to/source/repo",
      "name": "repo-name",
      "remote_url": "git@github.com:user/repo.git"
    },
    "target_repo": {
      "path": "/absolute/path/to/target/repo",
      "name": "target-repo-name",
      "remote_url": "git@github.com:user/target.git"
    }
  },
  "environment": {
    "node_version": "v20.x.x",
    "os": "darwin|linux|windows",
    "neotoma_env": "development|production"
  },
  "resolution_status": "pending|in_progress|resolved|failed",
  "resolution_notes": ""
}

Path Sanitization Rules

Repository Name Validation:

• Ensure repo name doesn't contain path traversal: .., /, \
• Allow only valid directory name characters: alphanumeric, hyphens, underscores, dots
• Reject repo names that don't match pattern: ^[a-zA-Z0-9._-]+$
• Example valid names: neotoma, personal-project, my_repo, repo.2
• Example invalid names: ../other, repo/subdir, ../../secret

Path Construction:

// Get current repo root
const currentRepoPath = execSync('git rev-parse --show-toplevel').toString().trim();

// If target repo name provided
if (targetRepoName) {
  // Sanitize repo name first
  if (!/^[a-zA-Z0-9._-]+$/.test(targetRepoName)) {
    throw new Error(`Invalid repo name: ${targetRepoName}. Only alphanumeric, hyphens, underscores, and dots allowed.`);
  }

  // Get parent directory
  const parentDir = path.dirname(currentRepoPath);

  // Construct target repo path
  const targetPath = path.join(parentDir, targetRepoName);

  return targetPath;
} else {
  // Use current repo
  return currentRepoPath;
}

Target Repository Validation

Before writing error report, validate target repository:

1. Path Exists:

   if (!fs.existsSync(targetPath)) {
     throw new Error(`Target repository not found: ${targetPath}`);
   }
   

2. Is Directory:

   if (!fs.statSync(targetPath).isDirectory()) {
     throw new Error(`Target path is not a directory: ${targetPath}`);
   }
   

3. Is Git Repository:

   const gitPath = path.join(targetPath, '.git');
   if (!fs.existsSync(gitPath)) {
     throw new Error(`Target path is not a git repository: ${targetPath}`);
   }
   

4. Is Writable:

   try {
     fs.accessSync(targetPath, fs.constants.W_OK);
   } catch {
     throw new Error(`No write permission for target repository: ${targetPath}`);
   }
   

If any validation fails, abort with clear error message and do not write error report.

Error Message Sanitization Rules

Apply these rules when generating reports:

1. Remove PII from error messages
2. Truncate stack traces to max 5000 characters
3. Replace sensitive paths with placeholders
4. Redact API keys, tokens, credentials
5. Remove user-specific data from file paths

Error Handling & User Feedback

Validation Failures:

1. Invalid Repo Name:

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

2. Target Repo Not Found:

   Error: Target repository not found: /Users/user/Projects/non-existent-repo
   
   Available sibling repositories:
   - neotoma
   - personal-project
   - another-repo
   

3. Not a Git Repository:

   Error: Target path is not a git repository: /Users/user/Projects/some-dir
   
   Target must be a git repository (contains .git directory).
   

4. No Write Permission:

   Error: No write permission for target repository: /Users/user/Projects/neotoma
   
   Check file permissions and try again.
   

Success Feedback:

Error report created successfully.

Error ID: 01JQZ8X9K2M3N4P5Q6R7S8T9U0
Category: build
Severity: high
Target: /Users/user/Projects/neotoma

Report saved to:
- /Users/user/Projects/neotoma/.cursor/error_reports/pending/error_20250131_143022_build.json
- /Users/user/Projects/neotoma/.cursor/error_reports/pending/error_20250131_143022_build.md

Added to pending queue for resolution.

Example Usage

Scenario 1: Auto-Detection from File Path

Agent: I encountered a TypeScript compilation error while building the project.

Error: Cannot find module '../db'
  at Object.<anonymous> (/Users/user/Projects/neotoma/src/services/raw_storage.ts:1:1)
  ...

Command: /report_error

Agent will:

1. Auto-detect target repo: Extract /Users/user/Projects/neotoma/ from stack trace → target: neotoma
2. Validate target repo exists and is writable
3. Classify as "build" error with "high" severity
4. Extract affected files: src/services/raw_storage.ts, etc.
5. Generate error report with sanitized paths
6. Save to neotoma repo's .cursor/error_reports/pending/error_20250131_143022_build.json
7. Add to neotoma's pending queue
8. Wait for resolution (default behavior)
9. Output summary with error ID and auto-detected target

Scenario 2: Auto-Detection from MCP Error

Agent: Working in personal-project repo, encountered MCP error.

Error: MCP error -32603: Failed to upload to storage: Bucket not found
Command: mcp_neotoma_ingest_structured

Command: /report_error

Agent will:

1. Auto-detect target repo: Extract mcp_neotoma from command context → target: neotoma
2. Resolve target repo: /Users/user/Projects/neotoma (sibling of personal-project)
3. Validate target repo exists and is writable
4. Classify as "runtime" error with "high" severity
5. Generate error report with repository metadata (source: personal-project, target: neotoma)
6. Save to neotoma repo's .cursor/error_reports/pending/
7. Add to neotoma's pending queue
8. Wait for resolution (default behavior)
9. Output summary showing auto-detected target repo path

Scenario 2b: Explicit Target (Overrides Auto-Detection)

Agent: Working in personal-project repo, want to explicitly report to neotoma.

Error: MCP error -32603: Failed to upload to storage: Bucket not found

Command: /report_error neotoma

Agent will:

1. Skip auto-detection (explicit target provided)
2. Resolve target repo: /Users/user/Projects/neotoma (sibling of personal-project)
3. Validate target repo exists and is writable
4. Classify as "runtime" error with "high" severity
5. Generate error report with repository metadata (source: personal-project, target: neotoma)
6. Save to neotoma repo's .cursor/error_reports/pending/
7. Add to neotoma's pending queue
8. Wait for resolution (default behavior)
9. Output summary showing target repo path

Scenario 3: Auto-Detection Fallback to Local

Agent: Encountered error with no clear repository origin.

Error: Generic runtime error
Command: /report_error

Agent will:

1. Attempt auto-detection: No MCP patterns, no clear repo paths found
2. Fallback to current repository (local reporting)
3. Log warning: "Could not auto-detect target repository, using current repo"
4. Generate error report
5. Save to current repo's .cursor/error_reports/pending/
6. Wait for resolution (default behavior)

Scenario 4: Invalid Target Repo

Command: /report_error ../secret-repo

Agent will:

1. Detect invalid repo name (contains ..)
2. Abort with error: "Invalid repo name: ../secret-repo. Only alphanumeric, hyphens, underscores, and dots allowed."
3. Do not create error report

Cross-Repo File Writing Logic

Directory Creation:

const errorReportsDir = path.join(targetRepoPath, '.cursor', 'error_reports');
const pendingDir = path.join(errorReportsDir, 'pending');
const resolvedDir = path.join(errorReportsDir, 'resolved');

// Create directories if they don't exist
fs.mkdirSync(errorReportsDir, { recursive: true });
fs.mkdirSync(pendingDir, { recursive: true });
fs.mkdirSync(resolvedDir, { recursive: true });

File Naming:

const timestamp = new Date().toISOString().replace(/[:.]/g, '').slice(0, 15);
const jsonFilename = `error_${timestamp}_${category}.json`;
const mdFilename = `error_${timestamp}_${category}.md`;

const jsonPath = path.join(pendingDir, jsonFilename);
const mdPath = path.join(pendingDir, mdFilename);

Write Error Reports:

// Write JSON report
fs.writeFileSync(jsonPath, JSON.stringify(errorReport, null, 2), 'utf8');

// Write Markdown summary
fs.writeFileSync(mdPath, markdownSummary, 'utf8');

// Update pending queue
const pendingPath = path.join(errorReportsDir, 'pending.json');
let pending = [];
if (fs.existsSync(pendingPath)) {
  pending = JSON.parse(fs.readFileSync(pendingPath, 'utf8'));
}
pending.push({
  error_id: errorReport.error_id,
  timestamp: errorReport.timestamp,
  category: errorReport.category,
  severity: errorReport.severity,
  file_path: jsonPath
});
fs.writeFileSync(pendingPath, JSON.stringify(pending, null, 2), 'utf8');

File Structure

Error reports are stored in the target repository's .cursor/error_reports/ directory:

target_repo/.cursor/
  error_reports/
    pending.json                           # Queue of errors awaiting resolution
    pending/                               # Pending error reports
      error_20250131_143022_build.json    # Individual error reports (JSON)
      error_20250131_143022_build.md      # Human-readable summaries (Markdown)
    resolved/                              # Archived resolved errors
      error_20250131_143022_build.json
      error_20250131_143022_build.md

Integration with Cursor Cloud Agent

The Cursor Cloud Agent will:

1. Monitor .cursor/error_reports/pending.json
2. Process errors in priority order (critical → low)
3. Update resolution_status when working on error
4. Move resolved errors from .cursor/error_reports/pending/ to .cursor/error_reports/resolved/
5. Add resolution notes to error report

Important for Wait Mode: When monitoring for resolution, the agent must check both pending/ and resolved/ directories, as the Cursor Cloud Agent moves files upon resolution. If a file is not found in pending/, check resolved/ before assuming the file is missing.

Integration with Existing Commands

With fix_feature_bug

• Errors classified as bugs can trigger the fix-feature-bug skill
• Agent can auto-classify certain error types as bugs
• Bug fix workflow will update error report resolution status

With analyze

• Can analyze error patterns across multiple reports
• Identify recurring issues
• Generate error trend reports

Configuration

Error reporting behavior can be configured in foundation-config.yaml:

development:
  error_reporting:
    enabled: true
    auto_detect: true  # Enable automatic target repository detection
    auto_classify_bugs: true
    severity_threshold: "medium"
    max_stack_trace_length: 5000
    retention_days: 30
    output_directory: ".cursor/error_reports"
    wait_by_default: true  # Enable wait mode by default (can disable with --no-wait)
    mcp_server_mapping:  # Map MCP server names to repository names
      neotoma: "neotoma"
      asana: "asana"
      gmail: "gmail"
      google_calendar: "google-calendar"
      google-calendar: "google-calendar"
    wait_mode:
      default_timeout: 300  # Default timeout in seconds (5 minutes)
      default_poll_interval: 5  # Default poll interval in seconds
      max_timeout: 3600  # Maximum allowed timeout (1 hour)
      min_poll_interval: 1  # Minimum allowed poll interval

Error Detection Patterns

Auto-detect errors matching these patterns:

• MCP error responses: MCP error -32603, UNKNOWN_CAPABILITY, etc.
• Build errors: TypeScript compilation failures, tsc errors
• Module resolution: Cannot find module, Module not found
• Runtime exceptions: Stack traces with Error:, Exception:
• Test failures: Test failed, AssertionError

Implementation Checklist

When reporting an error:

• Parse target-repo-name parameter (if provided)
• If target-repo-name not provided: Auto-detect target repository from error origin
  • Check for MCP error patterns (MCP error, mcp_ prefix)
  • Extract MCP server name from error message/stack trace
  • Check agent context for MCP command names
  • Check affected files for repository paths
  • Map detected source to sibling repository
  • Fallback to current repo if auto-detection fails
• Sanitize repo name (validate pattern)
• Resolve target repository path (parent_dir + repo_name or auto-detected)
• Validate target repository (exists, is git repo, writable)
• Extract error message and stack trace
• Classify error category
• Assign severity level
• Sanitize sensitive data
• Collect repository metadata (source and target)
• Generate unique error ID
• Create target repo directory structure if missing
• Create JSON report file in target repo (pending/ subdirectory)
• Create Markdown summary file in target repo (pending/ subdirectory)
• Update pending queue in target repo
• Output summary to user with target repo path (indicate if auto-detected)
• If wait mode enabled (default): Monitor error status until resolved or timeout

Example Error Report Files

JSON Report (error_20250131_143022_build.json)