# Job Processing with Real-Time Status Updates

This document describes the job YAML schema and how to update status fields for real-time UI updates.

## Job YAML Schema

Jobs are stored in `/home/aria/.openclaw/workspace/agency/jobs/{jobId}.yaml`

### Full Schema

```yaml
id: feedback-{slug}-{phase}-{timestamp}
action: phase-feedback
product_slug: product-slug
phase: market|build|sell
message:
  id: message-uuid
  content: "User's message text"
  user:
    name: "User Name"
    email: "user@example.com"
  attachments: []
chat_path: /path/to/chat.yaml

# Status fields (update these for real-time UI)
status: pending | processing | complete | error
progress: 0-100  # Percentage complete
current_step: "Human-readable status message"
steps_completed:
  - "Step 1 that was completed"
  - "Step 2 that was completed"
error: null | "Error message if failed"

# Timestamps
created_at: ISO timestamp
started_at: ISO timestamp (set when processing begins)
completed_at: ISO timestamp (set when done)
```

## Status Values

| Status | Description |
|--------|-------------|
| `pending` | Job created, waiting to be picked up |
| `processing` | ARIA is actively working on it |
| `complete` | Job finished successfully |
| `error` | Job failed with an error |

## How to Update Job Status (for ARIA)

When processing a job, update the YAML file with progress information:

### 1. When Starting

```yaml
status: processing
progress: 10
current_step: "Reading your feedback..."
started_at: 2025-02-07T06:30:00.000Z
```

### 2. During Processing

```yaml
status: processing
progress: 50
current_step: "Analyzing context and requirements..."
steps_completed:
  - "Read feedback and attachments"
  - "Loaded product context"
```

### 3. Near Completion

```yaml
status: processing
progress: 90
current_step: "Writing response..."
steps_completed:
  - "Read feedback and attachments"
  - "Loaded product context"
  - "Analyzed requirements"
```

### 4. When Complete

```yaml
status: complete
progress: 100
current_step: "Done!"
completed_at: 2025-02-07T06:35:00.000Z
```

### 5. On Error

```yaml
status: error
progress: 30  # Where it failed
current_step: "Failed to process request"
error: "Detailed error message"
```

## UI Behavior

The Symph Agency UI polls `/api/jobs/{id}` every 2 seconds when a user sends a message.

- **Progress bar**: Shows visual progress (only appears when progress > 0)
- **Current step**: Displayed as the main status text
- **Steps completed**: Shows last 3 completed steps with checkmarks
- **Error handling**: Red text for errors, 10-minute timeout for stuck jobs

## Example: Good Status Messages

| Step | Progress | Message |
|------|----------|---------|
| Start | 10% | "Reading your feedback..." |
| Context | 25% | "Loading product context..." |
| Analysis | 50% | "Analyzing requirements..." |
| Planning | 70% | "Planning response..." |
| Writing | 90% | "Writing detailed response..." |
| Done | 100% | "Done!" |

Keep messages:
- Short (under 40 chars)
- Action-oriented (verb + noun)
- Informative but not technical
