---
name: report
description: Generate report per foundation report command.
triggers:
  - report
  - /report
---

# 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

```bash
/report [target-repo-name] [--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:**
```bash
# Local reporting (current repo)
/report

# Cross-repo reporting to sibling repo
/report neotoma
/report personal-project

# Report error and wait for resolution
/report --wait

# Report error with custom timeout (10 minutes)
/report --wait --timeout 600

# Report error with custom poll interval (check every 2 seconds)
/report --wait --poll-interval 2

# Cross-repo reporting with wait mode
/report neotoma --wait --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:**
   ```bash
   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

```json
{
  "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:**
```javascript
// 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:**
   ```javascript
   if (!fs.existsSync(targetPath)) {
     throw new Error(`Target repository not found: ${targetPath}`);
   }
   ```

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

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

4. **Is Writable:**
   ```javascript
   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
```

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 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 ../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:**
```javascript
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:**
```javascript
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:**
```javascript
// 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`:

```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`)

**Example: Local Reporting**
```json
{
  "error_id": "01JQZ8X9K2M3N4P5Q6R7S8T9U0",
  "timestamp": "2025-01-31T14:30:22Z",
  "category": "build",
  "severity": "high",
  "error_message": "Cannot find module '../db'",
  "stack_trace": "Error: Cannot find module '../db'\n  at Object.<anonymous> (src/services/raw_storage.ts:1:1)\n  at Module._compile (node:internal/modules/cjs/loader:1376:14)\n  ...",
  "affected_files": [
    "src/services/raw_storage.ts",
    "src/services/interpretation.ts",
    "src/services/entity_queries.ts"
  ],
  "affected_modules": ["db"],
  "agent_context": {
    "agent_id": "cursor-agent",
    "task": "Transfer contacts from Parquet to Neotoma",
    "command": null
  },
  "repositories": {
    "source_repo": {
      "path": "/Users/user/Projects/neotoma",
      "name": "neotoma",
      "remote_url": "git@github.com:user/neotoma.git"
    },
    "target_repo": {
      "path": "/Users/user/Projects/neotoma",
      "name": "neotoma",
      "remote_url": "git@github.com:user/neotoma.git"
    }
  },
  "environment": {
    "node_version": "v20.11.0",
    "os": "darwin",
    "neotoma_env": "development"
  },
  "resolution_status": "pending",
  "resolution_notes": ""
}
```

**Example: Cross-Repo Reporting**
```json
{
  "error_id": "01JQZ8X9K2M3N4P5Q6R7S8T9U1",
  "timestamp": "2025-01-31T14:35:10Z",
  "category": "runtime",
  "severity": "high",
  "error_message": "MCP error -32603: Failed to upload to storage: Bucket not found",
  "stack_trace": "...",
  "affected_files": ["src/actions.ts"],
  "affected_modules": ["mcp_neotoma"],
  "agent_context": {
    "agent_id": "cursor-agent",
    "task": "Ingest structured contact data",
    "command": "ingest_structured"
  },
  "repositories": {
    "source_repo": {
      "path": "/Users/user/Projects/personal-project",
      "name": "personal-project",
      "remote_url": "git@github.com:user/personal-project.git"
    },
    "target_repo": {
      "path": "/Users/user/Projects/neotoma",
      "name": "neotoma",
      "remote_url": "git@github.com:user/neotoma.git"
    }
  },
  "environment": {
    "node_version": "v20.11.0",
    "os": "darwin",
    "neotoma_env": "development"
  },
  "resolution_status": "pending",
  "resolution_notes": ""
}
```

### Markdown Summary (`error_20250131_143022_build.md`)

**Example: Cross-Repo Reporting**
```markdown
# Error Report: Runtime Error

**Error ID:** `01JQZ8X9K2M3N4P5Q6R7S8T9U1`  
**Timestamp:** 2025-01-31T14:35:10Z  
**Category:** runtime  
**Severity:** high  
**Status:** pending

## Error Message

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

## Source Repository

- **Name:** personal-project
- **Path:** /Users/user/Projects/personal-project
- **Remote:** git@github.com:user/personal-project.git

## Target Repository

- **Name:** neotoma
- **Path:** /Users/user/Projects/neotoma
- **Remote:** git@github.com:user/neotoma.git

## Affected Files

- `src/actions.ts`

## Affected Modules

- mcp_neotoma

## Stack Trace

```
...
```

## Context

Agent was ingesting structured contact data when this runtime error occurred.

## Environment

- Node: v20.11.0
- OS: darwin
- Environment: development

## Resolution

Awaiting resolution by Cursor Cloud Agent.
```

## Best Practices

1. **Always sanitize**: Remove PII and sensitive data before storing
2. **Be specific**: Include relevant context about the task being performed
3. **Truncate wisely**: Keep stack traces informative but not excessive
4. **Update status**: Mark errors as resolved when fixed
5. **Archive old errors**: Move resolved errors to archive directory
6. **Review patterns**: Periodically analyze error reports for trends
7. **Use cross-repo reporting**: Report errors to appropriate repo (e.g., foundation errors to neotoma)
8. **Validate target repo**: Always validate target exists and is writable before attempting to write

## Testing Scenarios

### Test 1: Auto-Detection with MCP Error
```bash
/report
```
Error: "MCP error -32603: Failed to create interpretation run"
Expected: 
- Auto-detects target as `neotoma` (from `mcp_neotoma` in error context)
- Error report written to `../neotoma/.cursor/error_reports/pending/`
- Wait mode enabled by default

### Test 2: Explicit Target Repo (Overrides Auto-Detection)
```bash
/report neotoma
```
Expected: 
- Auto-detection skipped (explicit target provided)
- Error report written to `../neotoma/.cursor/error_reports/pending/`
- Wait mode enabled by default

### Test 3: Non-Existent Sibling Repo
```bash
/report non-existent-repo
```
Expected: Error message: "Target repository not found: /Users/user/Projects/non-existent-repo"

### Test 4: Invalid Repo Name (Path Traversal)
```bash
/report ../other-dir
```
Expected: Error message: "Invalid repo name: ../other-dir. Only alphanumeric, hyphens, underscores, and dots allowed."

### Test 5: Valid Name but Not Git Repo
```bash
/report some-directory
```
Expected: Error message: "Target path is not a git repository: /Users/user/Projects/some-directory"

### Test 6: Cross-Repo with Directory Creation
```bash
/report neotoma
```
(Where neotoma repo exists but `.cursor/error_reports/pending/` doesn't exist yet)
Expected: Directories created automatically, error report written successfully

## Wait-for-Resolution Mode

**Wait mode is enabled by default.** The agent will automatically monitor the error report status and wait for resolution before continuing, unless `--no-wait` is specified.

### Workflow with Wait Mode (Default)

1. **Report Error:**
   - Agent executes `/report --wait`
   - Error report created with `resolution_status: "pending"`
   - Error ID returned to agent
   - Auto-detection determines target repository if not specified

2. **Monitor Resolution:**
   - Agent polls error report file for status changes
   - **Important**: Check both `pending/` and `resolved/` directories, as resolved errors are moved from `pending/` to `resolved/` by the Cursor Cloud Agent
   - Checks `resolution_status` field in JSON report
   - Status values: `pending` → `in_progress` → `resolved` | `failed`

3. **Resolution Detection:**
   - **Resolved:** Status changes to `"resolved"`
     - Agent can resume/retry the operation that failed
     - Check `resolution_notes` for details about the fix
   - **Failed:** Status changes to `"failed"`
     - Agent should handle failure case (log, skip, or escalate)
     - Check `resolution_notes` for failure reason

4. **Timeout Handling:**
   - If timeout reached while status is still `pending` or `in_progress`:
     - Agent logs warning and continues (assumes resolution in progress)
     - Agent can check status later or proceed without waiting

5. **Resume/Retry Logic:**
   - After resolution, agent can:
     - **Resume:** Continue from where error occurred
     - **Retry:** Re-execute the operation that failed
     - **Skip:** If error indicates operation should be skipped

### Configuration

Wait mode settings are read from `foundation-config.yaml`:
- `error_reporting.wait_mode.default_timeout` - Default timeout (overridden by `--timeout`)
- `error_reporting.wait_mode.default_poll_interval` - Default poll interval (overridden by `--poll-interval`)
- `error_reporting.wait_mode.max_timeout` - Maximum allowed timeout
- `error_reporting.wait_mode.min_poll_interval` - Minimum allowed poll interval

### Auto-Detection Implementation

```javascript
function autoDetectTargetRepo(error, currentRepoPath) {
  const parentDir = path.dirname(currentRepoPath);
  
  // 1. Check for MCP errors
  if (error.message && error.message.includes('MCP error')) {
    // Extract MCP server name from error context
    const mcpMatch = error.message.match(/mcp_(\w+)/i) || 
                     error.stack?.match(/mcp_(\w+)/i);
    if (mcpMatch) {
      const serverName = mcpMatch[1];
      // Map common MCP servers to repos
      const repoMap = {
        'neotoma': 'neotoma',
        'asana': 'asana',
        'gmail': 'gmail',
        'google-calendar': 'google-calendar',
        'google_calendar': 'google-calendar'
      };
      const targetRepo = repoMap[serverName] || serverName;
      const targetPath = path.join(parentDir, targetRepo);
      if (fs.existsSync(targetPath) && fs.existsSync(path.join(targetPath, '.git'))) {
        return targetPath;
      }
    }
  }
  
  // 2. Check agent context for MCP commands
  if (error.agent_context?.command) {
    const cmd = error.agent_context.command;
    if (cmd.startsWith('mcp_')) {
      const serverName = cmd.split('_')[1];
      const targetPath = path.join(parentDir, serverName);
      if (fs.existsSync(targetPath) && fs.existsSync(path.join(targetPath, '.git'))) {
        return targetPath;
      }
    }
  }
  
  // 3. Check affected files/modules for repo paths
  if (error.affected_files) {
    for (const file of error.affected_files) {
      const repoMatch = file.match(/\/Projects\/([^\/]+)\//);
      if (repoMatch) {
        const repoName = repoMatch[1];
        const targetPath = path.join(parentDir, repoName);
        if (fs.existsSync(targetPath) && fs.existsSync(path.join(targetPath, '.git'))) {
          return targetPath;
        }
      }
    }
  }
  
  // 4. Fallback to current repo
  return currentRepoPath;
}
```

### Implementation Example

```javascript
// Agent workflow (wait mode enabled by default)
try {
  await performOperation();
} catch (error) {
  // Report error with auto-detection and wait for resolution (default)
  const result = await reportError('--timeout', '600');
  
  if (result.resolved) {
    // Retry operation after resolution
    console.log(`Retrying operation after error resolution: ${result.errorId}`);
    await performOperation(); // Retry
  } else if (result.failed) {
    // Handle failure case
    console.log(`Error resolution failed: ${result.resolutionNotes}`);
    throw new Error(`Operation failed and could not be resolved: ${result.errorId}`);
  } else if (result.timeout) {
    // Timeout - proceed or skip
    console.log(`Timeout waiting for resolution, skipping operation`);
    // Agent decides whether to skip or continue
  }
}
```

### Status Monitoring

The agent polls the error report JSON file for status changes. **Important**: When errors are resolved, the Cursor Cloud Agent moves the report files from `pending/` to `resolved/`. The wait logic must check both directories.

```javascript
async function waitForErrorResolution(errorId, errorReportPath, options = {}) {
  const {
    timeout = 300, // 5 minutes default
    pollInterval = 5, // 5 seconds default
  } = options;

  const startTime = Date.now();
  const timeoutMs = timeout * 1000;

  // Normalize error report path - extract base filename
  let baseFilename = path.basename(errorReportPath);
  if (!baseFilename.endsWith('.json')) {
    baseFilename = `${baseFilename}.json`;
  }

  // Get directory structure
  const errorReportsDir = path.dirname(path.dirname(errorReportPath)); // Go up from pending/ or resolved/
  const pendingDir = path.join(errorReportsDir, 'pending');
  const resolvedDir = path.join(errorReportsDir, 'resolved');

  // Start with pending path
  let currentPath = path.join(pendingDir, baseFilename);

  while (true) {
    // Check timeout
    if (Date.now() - startTime > timeoutMs) {
      throw new Error(`Timeout waiting for error resolution: ${errorId}`);
    }

    // Check if file exists in pending/ or resolved/
    let reportPath = null;
    if (fs.existsSync(path.join(pendingDir, baseFilename))) {
      reportPath = path.join(pendingDir, baseFilename);
    } else if (fs.existsSync(path.join(resolvedDir, baseFilename))) {
      reportPath = path.join(resolvedDir, baseFilename);
    } else {
      // File not found in either location - might have been deleted or moved
      throw new Error(`Error report file not found: ${baseFilename}`);
    }

    // Read error report
    const report = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
    const status = report.resolution_status;

    // Check if resolved or failed
    if (status === 'resolved') {
      return {
        status: 'resolved',
        errorId,
        resolutionNotes: report.resolution_notes || '',
        report,
        reportPath // Return actual path (may be in resolved/)
      };
    }

    if (status === 'failed') {
      return {
        status: 'failed',
        errorId,
        resolutionNotes: report.resolution_notes || '',
        report,
        reportPath // Return actual path (may be in resolved/)
      };
    }

    // Still pending or in_progress, wait and check again
    console.log(`[WAIT] Error ${errorId} status: ${status}, waiting...`);
    await new Promise(resolve => setTimeout(resolve, pollInterval * 1000));
  }
}
```

### Shell Script Example

For shell-based implementations, check both directories:

```bash
ERROR_REPORT_PATH="/path/to/target/.cursor/error_reports/pending/error_TIMESTAMP_runtime.json"
ERROR_REPORTS_DIR="/path/to/target/.cursor/error_reports"
PENDING_DIR="$ERROR_REPORTS_DIR/pending"
RESOLVED_DIR="$ERROR_REPORTS_DIR/resolved"
BASE_FILENAME=$(basename "$ERROR_REPORT_PATH")

TIMEOUT=300
POLL_INTERVAL=5
START_TIME=$(date +%s)

while true; do
  CURRENT_TIME=$(date +%s)
  ELAPSED=$((CURRENT_TIME - START_TIME))
  
  # Check timeout
  if [ $ELAPSED -ge $TIMEOUT ]; then
    echo "⏱️  Timeout reached (${TIMEOUT}s) while waiting for resolution"
    # Check final status in either directory
    if [ -f "$RESOLVED_DIR/$BASE_FILENAME" ]; then
      STATUS=$(cat "$RESOLVED_DIR/$BASE_FILENAME" | jq -r '.resolution_status' || echo "unknown")
    elif [ -f "$PENDING_DIR/$BASE_FILENAME" ]; then
      STATUS=$(cat "$PENDING_DIR/$BASE_FILENAME" | jq -r '.resolution_status' || echo "unknown")
    else
      STATUS="unknown"
    fi
    echo "Final status: $STATUS"
    exit 0
  fi
  
  # Check both pending/ and resolved/ directories
  REPORT_PATH=""
  if [ -f "$PENDING_DIR/$BASE_FILENAME" ]; then
    REPORT_PATH="$PENDING_DIR/$BASE_FILENAME"
  elif [ -f "$RESOLVED_DIR/$BASE_FILENAME" ]; then
    REPORT_PATH="$RESOLVED_DIR/$BASE_FILENAME"
  else
    echo "⚠️  Error report file not found in pending/ or resolved/: $BASE_FILENAME"
    exit 1
  fi
  
  # Read status
  STATUS=$(cat "$REPORT_PATH" | jq -r '.resolution_status' 2>/dev/null || echo "pending")
  echo "[WAIT] Error status: $STATUS (elapsed: ${ELAPSED}s)"
  
  # Check if resolved or failed
  if [ "$STATUS" = "resolved" ]; then
    echo "✅ Error resolved!"
    cat "$REPORT_PATH" | jq -r '.resolution_notes // "No resolution notes provided."'
    exit 0
  fi
  
  if [ "$STATUS" = "failed" ]; then
    echo "❌ Error resolution failed"
    cat "$REPORT_PATH" | jq -r '.resolution_notes // "No failure reason provided."'
    exit 1
  fi
  
  # Still pending or in_progress, wait and check again
  sleep $POLL_INTERVAL
done
```

## Helper Scripts

The following scripts are provided in `foundation/scripts/` to simplify error reporting implementation. These can be used by agents when implementing the `/report_error` command.

**Script Location:** `foundation/scripts/report_error_*.sh`

**Usage:** Scripts can be called directly from the foundation submodule, or copied/referenced as needed.

### Script: Validate Target Repository

**File:** `foundation/scripts/report_error_validate_target.sh`

```bash
#!/bin/bash
# validate_target_repo.sh
# Usage: validate_target_repo.sh <target-repo-path>

TARGET_REPO="$1"

if [ -z "$TARGET_REPO" ]; then
  echo "❌ Error: Target repository path required"
  exit 1
fi

# Check if path exists
if [ ! -d "$TARGET_REPO" ]; then
  echo "❌ Error: Target repository not found: $TARGET_REPO"
  exit 1
fi

# Check if it's a git repository
if [ ! -d "$TARGET_REPO/.git" ]; then
  echo "❌ Error: Target path is not a git repository: $TARGET_REPO"
  exit 1
fi

# Check write permissions
if [ ! -w "$TARGET_REPO" ]; then
  echo "❌ Error: No write permission for target repository: $TARGET_REPO"
  exit 1
fi

echo "✅ Target repository validated: $TARGET_REPO"
exit 0
```

### Script: Generate Error ID and Timestamp

**File:** `foundation/scripts/report_error_generate_id.sh`

```bash
#!/bin/bash
# generate_error_id.sh
# Outputs: ERROR_ID|TIMESTAMP

TIMESTAMP=$(date -u +"%Y%m%dT%H%M%S")
ERROR_ID="01JQ$(echo $TIMESTAMP | tr -d 'T' | cut -c1-20)"
echo "${ERROR_ID}|${TIMESTAMP}"
```

### Script: Create Error Report Directories

**File:** `foundation/scripts/report_error_create_dirs.sh`

```bash
#!/bin/bash
# create_error_report_dirs.sh
# Usage: create_error_report_dirs.sh <target-repo-path>

TARGET_REPO="$1"
ERROR_REPORTS_DIR="$TARGET_REPO/.cursor/error_reports"
PENDING_DIR="$ERROR_REPORTS_DIR/pending"
RESOLVED_DIR="$ERROR_REPORTS_DIR/resolved"

mkdir -p "$PENDING_DIR" "$RESOLVED_DIR"
echo "✅ Created error report directories in $TARGET_REPO"
```

### Script: Create Error Report Files

```bash
#!/bin/bash
# create_error_report.sh
# Usage: create_error_report.sh <target-repo-path> <error-id> <timestamp> <category> <severity> <error-message> <json-data>

TARGET_REPO="$1"
ERROR_ID="$2"
TIMESTAMP="$3"
CATEGORY="$4"
SEVERITY="$5"
ERROR_MSG="$6"
JSON_DATA="$7"

ERROR_REPORTS_DIR="$TARGET_REPO/.cursor/error_reports"
PENDING_DIR="$ERROR_REPORTS_DIR/pending"

# Generate filenames
JSON_FILENAME="error_${TIMESTAMP}_${CATEGORY}.json"
MD_FILENAME="error_${TIMESTAMP}_${CATEGORY}.md"
JSON_PATH="$PENDING_DIR/$JSON_FILENAME"
MD_PATH="$PENDING_DIR/$MD_FILENAME"

# Write JSON report
echo "$JSON_DATA" > "$JSON_PATH"

# Generate Markdown summary
cat > "$MD_PATH" << EOF
# Error Report: $(echo $CATEGORY | tr '[:lower:]' '[:upper:]') Error

**Error ID:** \`$ERROR_ID\`  
**Timestamp:** $(echo $TIMESTAMP | sed 's/\(....\)\(..\)\(..\)T\(..\)\(..\)\(..\)/\1-\2-\3T\4:\5:\6Z/')  
**Category:** $CATEGORY  
**Severity:** $SEVERITY  
**Status:** pending

## Error Message

$ERROR_MSG

## Resolution

Awaiting resolution by Cursor Cloud Agent.
EOF

echo "$JSON_PATH|$MD_PATH"
```

### Script: Update Pending Queue

```bash
#!/bin/bash
# update_pending_queue.sh
# Usage: update_pending_queue.sh <target-repo-path> <error-id> <timestamp> <category> <severity> <json-path>

TARGET_REPO="$1"
ERROR_ID="$2"
TIMESTAMP="$3"
CATEGORY="$4"
SEVERITY="$5"
JSON_PATH="$6"

PENDING_FILE="$TARGET_REPO/.cursor/error_reports/pending.json"
NEW_ENTRY="{\"error_id\": \"$ERROR_ID\", \"timestamp\": \"$(echo $TIMESTAMP | sed 's/\(....\)\(..\)\(..\)T\(..\)\(..\)\(..\)/\1-\2-\3T\4:\5:\6Z/')\", \"category\": \"$CATEGORY\", \"severity\": \"$SEVERITY\", \"file_path\": \"$JSON_PATH\"}"

if [ -f "$PENDING_FILE" ]; then
  cat "$PENDING_FILE" | jq ". + [$NEW_ENTRY]" > "$PENDING_FILE.tmp" && mv "$PENDING_FILE.tmp" "$PENDING_FILE"
else
  echo "[$NEW_ENTRY]" > "$PENDING_FILE"
fi

echo "✅ Pending queue updated"
```

### Script: Wait for Error Resolution

**File:** `foundation/scripts/report_error_wait_resolution.sh`

```bash
#!/bin/bash
# wait_for_resolution.sh
# Usage: wait_for_resolution.sh <target-repo-path> <base-filename> [timeout] [poll-interval]

TARGET_REPO="$1"
BASE_FILENAME="$2"
TIMEOUT="${3:-300}"
POLL_INTERVAL="${4:-5}"

ERROR_REPORTS_DIR="$TARGET_REPO/.cursor/error_reports"
PENDING_DIR="$ERROR_REPORTS_DIR/pending"
RESOLVED_DIR="$ERROR_REPORTS_DIR/resolved"

START_TIME=$(date +%s)

while true; do
  CURRENT_TIME=$(date +%s)
  ELAPSED=$((CURRENT_TIME - START_TIME))
  
  # Check timeout
  if [ $ELAPSED -ge $TIMEOUT ]; then
    echo "⏱️  Timeout reached (${TIMEOUT}s) while waiting for resolution"
    # Check final status in either directory
    if [ -f "$RESOLVED_DIR/$BASE_FILENAME" ]; then
      STATUS=$(cat "$RESOLVED_DIR/$BASE_FILENAME" | jq -r '.resolution_status' || echo "unknown")
    elif [ -f "$PENDING_DIR/$BASE_FILENAME" ]; then
      STATUS=$(cat "$PENDING_DIR/$BASE_FILENAME" | jq -r '.resolution_status' || echo "unknown")
    else
      STATUS="unknown"
    fi
    echo "Final status: $STATUS"
    exit 0
  fi
  
  # Check both pending/ and resolved/ directories
  REPORT_PATH=""
  if [ -f "$PENDING_DIR/$BASE_FILENAME" ]; then
    REPORT_PATH="$PENDING_DIR/$BASE_FILENAME"
  elif [ -f "$RESOLVED_DIR/$BASE_FILENAME" ]; then
    REPORT_PATH="$RESOLVED_DIR/$BASE_FILENAME"
  else
    echo "⚠️  Error report file not found in pending/ or resolved/: $BASE_FILENAME"
    exit 1
  fi
  
  # Read status
  STATUS=$(cat "$REPORT_PATH" | jq -r '.resolution_status' 2>/dev/null || echo "pending")
  echo "[WAIT] Error status: $STATUS (elapsed: ${ELAPSED}s)"
  
  # Check if resolved or failed
  if [ "$STATUS" = "resolved" ]; then
    echo "✅ Error resolved!"
    cat "$REPORT_PATH" | jq -r '.resolution_notes // "No resolution notes provided."'
    exit 0
  fi
  
  if [ "$STATUS" = "failed" ]; then
    echo "❌ Error resolution failed"
    cat "$REPORT_PATH" | jq -r '.resolution_notes // "No failure reason provided."'
    exit 1
  fi
  
  # Still pending or in_progress, wait and check again
  sleep $POLL_INTERVAL
done
```

### Complete Workflow Script

```bash
#!/bin/bash
# report_error_workflow.sh
# Complete workflow for reporting an error
# Usage: report_error_workflow.sh <target-repo-name> <error-message> <category> <severity> [--no-wait] [--timeout SECONDS]

set -e

# Parse arguments
TARGET_REPO_NAME="$1"
ERROR_MSG="$2"
CATEGORY="$3"
SEVERITY="$4"
NO_WAIT=false
TIMEOUT=300

shift 4
while [[ $# -gt 0 ]]; do
  case $1 in
    --no-wait)
      NO_WAIT=true
      shift
      ;;
    --timeout)
      TIMEOUT="$2"
      shift 2
      ;;
    *)
      shift
      ;;
  esac
done

# Get current repo path
CURRENT_REPO=$(git rev-parse --show-toplevel)
PARENT_DIR=$(dirname "$CURRENT_REPO")

# Resolve target repo
if [ -n "$TARGET_REPO_NAME" ]; then
  TARGET_REPO="$PARENT_DIR/$TARGET_REPO_NAME"
else
  # Auto-detect (simplified - would need full MCP detection logic)
  TARGET_REPO="$CURRENT_REPO"
fi

# Validate target repo
if [ ! -d "$TARGET_REPO" ] || [ ! -d "$TARGET_REPO/.git" ]; then
  echo "❌ Error: Invalid target repository: $TARGET_REPO"
  exit 1
fi

# Generate error ID and timestamp
ID_TIMESTAMP=$(TIMESTAMP=$(date -u +"%Y%m%dT%H%M%S") && ERROR_ID="01JQ$(echo $TIMESTAMP | tr -d 'T' | cut -c1-20)" && echo "${ERROR_ID}|${TIMESTAMP}")
ERROR_ID=$(echo "$ID_TIMESTAMP" | cut -d'|' -f1)
TIMESTAMP=$(echo "$ID_TIMESTAMP" | cut -d'|' -f2)

# Create directories
mkdir -p "$TARGET_REPO/.cursor/error_reports/pending" "$TARGET_REPO/.cursor/error_reports/resolved"

# Create error report (simplified - would need full JSON structure)
JSON_FILENAME="error_${TIMESTAMP}_${CATEGORY}.json"
JSON_PATH="$TARGET_REPO/.cursor/error_reports/pending/$JSON_FILENAME"

# Generate JSON report (simplified structure)
cat > "$JSON_PATH" << EOF
{
  "error_id": "$ERROR_ID",
  "timestamp": "$(echo $TIMESTAMP | sed 's/\(....\)\(..\)\(..\)T\(..\)\(..\)\(..\)/\1-\2-\3T\4:\5:\6Z/')",
  "category": "$CATEGORY",
  "severity": "$SEVERITY",
  "error_message": "$(echo "$ERROR_MSG" | jq -Rs .)",
  "resolution_status": "pending",
  "resolution_notes": ""
}
EOF

# Update pending queue
PENDING_FILE="$TARGET_REPO/.cursor/error_reports/pending.json"
NEW_ENTRY="{\"error_id\": \"$ERROR_ID\", \"timestamp\": \"$(echo $TIMESTAMP | sed 's/\(....\)\(..\)\(..\)T\(..\)\(..\)\(..\)/\1-\2-\3T\4:\5:\6Z/')\", \"category\": \"$CATEGORY\", \"severity\": \"$SEVERITY\", \"file_path\": \"$JSON_PATH\"}"
if [ -f "$PENDING_FILE" ]; then
  cat "$PENDING_FILE" | jq ". + [$NEW_ENTRY]" > "$PENDING_FILE.tmp" && mv "$PENDING_FILE.tmp" "$PENDING_FILE"
else
  echo "[$NEW_ENTRY]" > "$PENDING_FILE"
fi

echo "Error report created successfully."
echo "Error ID: $ERROR_ID"
echo "Category: $CATEGORY"
echo "Severity: $SEVERITY"
echo "Target: $TARGET_REPO"
echo "Report saved to: $JSON_PATH"

# Wait for resolution if enabled
if [ "$NO_WAIT" = false ]; then
  echo ""
  echo "⏳ Waiting for resolution (timeout: ${TIMEOUT}s)..."
  BASE_FILENAME=$(basename "$JSON_PATH")
  "$(dirname "$0")/wait_for_resolution.sh" "$TARGET_REPO" "$BASE_FILENAME" "$TIMEOUT"
fi
```

### Usage in Agent Implementation

Agents can use these scripts as building blocks. Scripts are located in `foundation/scripts/`:

```bash
# Example: Report error using helper scripts
FOUNDATION_DIR="foundation"  # or path to foundation submodule
TARGET_REPO_NAME="neotoma"
CURRENT_REPO=$(git rev-parse --show-toplevel)
PARENT_DIR=$(dirname "$CURRENT_REPO")
TARGET_REPO="$PARENT_DIR/$TARGET_REPO_NAME"

# Validate target repository
"$FOUNDATION_DIR/scripts/report_error_validate_target.sh" "$TARGET_REPO"

# Generate error ID and timestamp
ID_TIMESTAMP=$("$FOUNDATION_DIR/scripts/report_error_generate_id.sh")
ERROR_ID=$(echo "$ID_TIMESTAMP" | cut -d'|' -f1)
TIMESTAMP=$(echo "$ID_TIMESTAMP" | cut -d'|' -f2)

# Create directories
"$FOUNDATION_DIR/scripts/report_error_create_dirs.sh" "$TARGET_REPO"

# ... create error report files (JSON and Markdown) ...
# ... update pending queue ...

# Wait for resolution (if wait mode enabled)
BASE_FILENAME="error_${TIMESTAMP}_runtime.json"
"$FOUNDATION_DIR/scripts/report_error_wait_resolution.sh" "$TARGET_REPO" "$BASE_FILENAME" 300 5
```

**Note:** If `foundation` is a submodule, use the relative path from the repository root. If scripts are symlinked or copied, adjust paths accordingly.

## Related Documentation

- Skill `fix-feature-bug` (`.cursor/skills/fix-feature-bug/SKILL.md`) - Bug fix workflow
- Skill `analyze` (`.cursor/skills/analyze/SKILL.md`) - Analysis workflow
- Skill `debug` (`.cursor/skills/debug/SKILL.md`) - Debug workflow
- `foundation-config.yaml` - Configuration file (in repository root)