Skill: Workflow Trace

Purpose

Provide real-time visibility into workflow execution, showing current step, progress, blockers, and full execution trace for debugging and monitoring.

When to Use

• Workflow monitoring
• Progress tracking
• Blocker identification
• Performance analysis
• Debugging workflow issues
• Stakeholder status updates

---

Trace Components

Workflow Status

Status	Icon	Description
Not Started	⚪	Workflow queued
In Progress	🔄	Currently executing
Blocked	🚫	Waiting on input/dependency
Completed	✅	Successfully finished
Failed	❌	Error occurred
Cancelled	⏹️	Manually cancelled

Step Status

Status	Icon	Description
Pending	⏳	Not yet started
Active	🔄	Currently executing
Blocked	🚫	Waiting on something
Completed	✅	Step finished
Skipped	⏭️	Conditionally skipped
Failed	❌	Step failed

---

Trace Structure

Workflow Trace Record

interface WorkflowTrace {
  // Identity
  trace_id: string;
  workflow_name: string;
  workflow_version: string;

  // Timing
  started_at: string;
  ended_at?: string;
  duration_ms?: number;

  // Status
  status: WorkflowStatus;
  current_step?: string;
  current_agent?: string;

  // Progress
  steps: Array<{
    step_number: number;
    step_name: string;
    agent: string;
    status: StepStatus;
    started_at?: string;
    ended_at?: string;
    duration_ms?: number;

    // Step details
    input?: any;
    output?: any;
    decisions?: string[];
    artifacts?: string[];
    error?: string;
  }>;

  // Blockers
  blockers: Array<{
    step: string;
    description: string;
    waiting_for: string;
    since: string;
    resolution?: string;
  }>;

  // Artifacts
  artifacts_created: string[];

  // Context
  trigger: string;
  initiator: string;
  related_tickets: string[];
}

---

Trace Visualization

Progress View

## Workflow: {{workflow_name}}

**Status:** {{status_icon}} {{status}}
**Started:** {{start_time}}
**Duration:** {{duration}}

### Progress

{{step_visualization}}

Example: ✅ Step 1: Orchestrator Receives (5 min) ✅ Step 2: BA Analyzes (25 min) 🔄 Step 3: PO Validates (in progress) ⏳ Step 4: Architect Reviews ⏳ Step 5: QA Reviews ⏳ Step 6: Orchestrator Finalizes

### Current Step

**Agent:** {{current_agent}}
**Step:** {{current_step}}
**Started:** {{step_start}}
**Duration:** {{step_duration}}

Timeline View

## Workflow Timeline

Time (minutes) 0 5 10 15 20 25 30 35 40 |----|----|----|----|----|----|----|----| [Orchestrator ] [ Business Analyst ] [PO...]

### Step Details

| Step | Agent | Start | End | Duration | Status |
|------|-------|-------|-----|----------|--------|
{{step_table}}

### Performance

- Total Duration: {{total_duration}}
- Longest Step: {{longest_step}} ({{longest_duration}})
- Average Step: {{avg_duration}}

Blocker View

## Current Blockers

### 🚫 Blocker: {{blocker_description}}

**Step:** {{blocked_step}}
**Agent:** {{blocked_agent}}
**Since:** {{blocked_since}} ({{blocked_duration}})

**Waiting For:**
{{waiting_for}}

**Impact:**
- Workflow delayed by {{delay}}
- Downstream steps affected: {{affected_steps}}

**Resolution Options:**
1. {{resolution_1}}
2. {{resolution_2}}

**Escalated To:** {{escalation_target}}

---

Trace Queries

Active Workflows

## Active Workflows

| Workflow | Status | Current Step | Agent | Duration |
|----------|--------|--------------|-------|----------|
{{active_workflows}}

### Summary
- Active: {{active_count}}
- Blocked: {{blocked_count}}
- Avg Duration: {{avg_duration}}

Workflow History

## Workflow History: {{workflow_name}}

### Last 10 Executions

| Trace ID | Started | Status | Duration | Artifacts |
|----------|---------|--------|----------|-----------|
{{history_table}}

### Statistics
- Success Rate: {{success_rate}}%
- Avg Duration: {{avg_duration}}
- Common Blockers: {{common_blockers}}

Trace Details

## Trace: {{trace_id}}

### Overview
- Workflow: {{workflow_name}}
- Status: {{status}}
- Duration: {{duration}}
- Artifacts: {{artifact_count}}

### Execution Log

{{execution_log}}

### Decisions Made

{{decisions_list}}

### Artifacts Created

{{artifacts_list}}

---

Real-time Updates

Webhook Events

interface TraceEvent {
  event_type: 'step_started' | 'step_completed' | 'blocked' | 'decision' | 'completed';
  trace_id: string;
  timestamp: string;
  data: {
    step?: string;
    agent?: string;
    details?: any;
  };
}

Polling Endpoint

## Status Check

**Endpoint:** /workflow/{{trace_id}}/status

**Response:**
```json
{
  "status": "in_progress",
  "current_step": "PO Validates",
  "progress": 3,
  "total_steps": 6,
  "percent_complete": 50,
  "estimated_remaining": "15 minutes",
  "blockers": []
}

---

## Performance Analysis

### Step Performance

```markdown
## Step Performance Analysis

### {{workflow_name}} - Last 30 Days

| Step | Avg Duration | P50 | P95 | Trend |
|------|--------------|-----|-----|-------|
{{step_performance}}

### Bottlenecks Identified

1. **{{bottleneck_step}}**: {{bottleneck_analysis}}
   - Recommendation: {{recommendation}}

### Performance Trends

{{trend_chart}}

---

Agents Using This Skill

• Orchestrator - Workflow monitoring
• Project Manager - Progress reporting
• All Agents - Step reporting

Related Skills

• observability-activity-log - Detailed activity
• observability-decision-trail - Decision tracking
• jira-reporting - Status reporting

MCP Tools Used

• Atlassian:addCommentToJiraIssue - Progress updates
• Atlassian:createConfluencePage - Trace documentation