---
name: fluent-job-batch
description: Diagnose and monitor JOB/BATCH orchestration entity lifecycles in Fluent Commerce. Covers JOB and BATCH entity workflows, status tracking, failure investigation, and performance monitoring. Distinct from batch data ingestion API. Triggers on "job batch", "batch management", "job lifecycle", "job status", "batch monitoring", "batch operations", "job entity".
user-invocable: true
read-only: true
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
argument-hint: [--job-id <id>] [--batch-id <id>] [--status ACTIVE|COMPLETED|FAILED]
cursor-tier: auto
---

# JOB/BATCH Orchestration Lifecycle

Monitor and diagnose JOB and BATCH entity orchestration workflows in Fluent Commerce.

## Ownership Boundary

This skill owns JOB/BATCH entity lifecycle diagnostics and monitoring.

- **Batch data ingestion API** (batch.create/send/status/results) → `/fluent-mcp-tools`
- **Event query syntax** → `/fluent-event-api`
- **Root cause diagnosis** → `/fluent-trace`
- **Workflow structure** → `/fluent-workflow-analyzer`

## Skill Type: Reference

This is a **reference skill** — it provides diagnostic patterns and monitoring guidance for JOB/BATCH entity lifecycles but does not modify code or environments. Implementation changes (workflow edits, batch API calls) should be delegated to the appropriate skills listed in the Ownership Boundary above.

## Disambiguation: JOB/BATCH Orchestration vs Batch Ingestion API

| Concept | What It Is | Skill |
|---------|-----------|-------|
| **JOB entity** | Root orchestratable entity with its own workflow (like ORDER or LOCATION) | This skill |
| **BATCH entity** | Child entity of JOB, progresses through workflow states | This skill |
| **batch.create/send/status/results** | MCP tools for uploading data records to Fluent via batch ingestion | `/fluent-mcp-tools` |

The batch ingestion API *creates* JOB and BATCH entities. This skill covers what happens *after* creation — the orchestration lifecycle.

## JOB Entity Lifecycle

JOB is one of the 10 root entity types that can have orchestration workflows.

### Status Flow
```
ACTIVE → COMPLETED (all batches succeeded)
ACTIVE → FAILED (one or more batches failed)
```

### Key Behaviors
- **Auto-close:** JOB entities automatically close at midnight UTC
- **Workflow type:** `JOB::<subtype>` (subtype varies by implementation)
- **Root entity:** JOB is always its own root entity in event context

## BATCH Entity Lifecycle

BATCH entities are children of JOB, similar to how FULFILMENT is a child of ORDER.

### Status Flow
```
CREATE → BATCH_COMPLETE
```

### Key Behaviors
- **Operations:** Each BATCH contains multiple GraphQL mutations and webhook calls
- **Metrics:** Success rates, operation counts, performance tracking per batch

## Diagnostic Queries

### Find JOB Events
```
event.list({
  "context.entityType": "JOB",
  "eventType": "ORCHESTRATION",
  "from": "<time_window_start>",
  "count": 50
})
```

### Find BATCH Events for a JOB
```
event.list({
  "context.rootEntityType": "JOB",
  "context.rootEntityId": "<JOB_ID>",
  "context.entityType": "BATCH",
  "count": 100
})
```

### Find Failed Batches
```
event.list({
  "context.entityType": "BATCH",
  "eventStatus": "FAILED",
  "from": "<time_window_start>",
  "count": 50
})
```

> **Canonical reference:** See `/fluent-event-api` for complete event status values, filter syntax, and query patterns.

### Query JOB Entity State
```graphql
{
  jobs(id: [<JOB_ID>], first: 1) {
    edges {
      node {
        id
        ref
        status
        type
        createdOn
        updatedOn
        attributes { name type value }
      }
    }
  }
}
```

Note: The `jobs` GraphQL query root may not exist in all Fluent versions. If unavailable, use event.list to track JOB lifecycle via events.

## Troubleshooting

### JOB Stuck in ACTIVE

> **Event filter reference:** For complete filter syntax, see `/fluent-event-api`. The examples below show batch-specific patterns.

1. Check if batches are still processing: query BATCH events for the JOB
2. Check if auto-close time has passed (midnight UTC)
3. Check for exceptions: `event.list({ category: "exception", "context.rootEntityType": "JOB", "context.rootEntityId": "<ID>" })`

### BATCH Failed
1. Get exception details: `event.list({ category: "exception", "context.entityType": "BATCH", "context.entityId": "<BATCH_ID>" })`
2. Check operation details in event attributes
3. Hand off to `/fluent-trace` for root cause analysis

### Performance Issues
1. Check batch operation timing via `startTimer`/`stopTimer` in audit events
2. Use `metrics.topEvents` to see if JOB/BATCH events are unusually high-volume
3. Compare batch sizes and operation counts across jobs

## Integration with Other Skills

| Need | Skill |
|------|-------|
| Batch data upload (batch.create/send) | `/fluent-mcp-tools` |
| Event query syntax and filters | `/fluent-event-api` |
| Root cause for failed batches | `/fluent-trace` |
| JOB workflow structure | `/fluent-workflow-analyzer` |
| Event volume analytics | `/fluent-system-monitoring` |
