---
name: ao-time-report
description: "View accumulated time-tracking data. Summary by epic, issue, command. Session details with durations. Filter by date range, epic, or issue."
category: extended
invokes: [ao-state]
invoked_by: []
state_files:
  read: [time-tracking.jsonl]
  write: []
arguments:
  - name: view
    type: enum
    values: [summary, epic, issue, command, sessions, active]
    default: summary
    description: "Report view: summary=overall stats, epic=grouped by epic, issue=grouped by issue, command=by command type, sessions=session list, active=current session"
  - name: epic
    type: string
    default: ""
    description: "Filter by epic name (e.g., 'Authentication')"
  - name: issue
    type: string
    default: ""
    description: "Filter by issue ID (e.g., 'FEAT-0001@abc123')"
  - name: days
    type: integer
    default: 0
    description: "Filter to last N days (0=all time)"
---

# Time Report Skill

View accumulated time-tracking data from `.agent/ops/time-tracking.jsonl`.

## Time Tracking Overview

Time is automatically tracked by `ao-state` whenever any skill is invoked:
- Sessions are appended as events (`session_start`, `session_heartbeat`, `session_end`)
- 5-minute timeout ends a session and starts a new one
- Time is associated with issues, epics, and commands
- **Aggregation is computed on-the-fly** by scanning `session_end` events — no stored summary

## Report Views

### 1. Summary View (default)

Overall time statistics across all tracked work.

```markdown
# Time Tracking Summary

## Overview
| Metric | Value |
|--------|-------|
| Total Time Tracked | 4h 0m (240 min) |
| Total Sessions | 12 |
| Avg Session Duration | 20 min |
| Active Session | Yes (started 18:35) |

## By Epic
| Epic | Time | % | Sessions |
|------|------|---|----------|
| Authentication | 3h 0m (180 min) | 75% | 8 |
| Dashboard | 1h 0m (60 min) | 25% | 4 |

## By Issue
| Issue | Time | Sessions | Epic |
|-------|------|----------|------|
| FEAT-0001@abc123 | 2h 25m (145 min) | 6 | Authentication |
| FEAT-0002@def456 | 1h 35m (95 min) | 6 | Dashboard |

## By Command
| Command | Time | Sessions |
|---------|------|----------|
| ao-implement | 2h 0m (120 min) | 6 |
| ao-plan | 1h 0m (60 min) | 3 |
| ao-validation | 30m | 2 |
| ao-testing | 30m | 1 |
```

### 2. Epic View

Time breakdown for a specific epic.

```markdown
# Epic Time Report: Authentication

## Summary
| Metric | Value |
|--------|-------|
| Total Time | 3h 0m (180 min) |
| Sessions | 8 |
| Issues | 2 |
| Avg per Issue | 90 min |

## By Issue
| Issue | Time | Sessions |
|-------|------|----------|
| FEAT-0001@abc123 — Login form | 2h 25m (145 min) | 6 |
| FEAT-0005@xyz789 — Password reset | 35m | 2 |

## Recent Sessions
| Time | Duration | Commands |
|------|----------|----------|
| Today 18:00-18:30 | 30m | ao-implement |
| Today 14:00-14:15 | 15m | ao-plan |
| Yesterday 16:00-17:00 | 60m | ao-implement, ao-testing |
```

### 3. Issue View

Detailed time tracking for a specific issue.

```markdown
# Issue Time Report: FEAT-0001@abc123

## Summary
| Metric | Value |
|--------|-------|
| Issue | FEAT-0001@abc123 — Login form |
| Epic | Authentication |
| Total Time | 2h 25m (145 min) |
| Sessions | 6 |
| First Worked | 2026-01-28 14:00 |
| Last Worked | 2026-02-02 18:30 |

## Sessions
| Date | Time | Duration | Commands |
|------|------|----------|----------|
| Feb 2 | 18:00-18:30 | 30m | ao-implement |
| Feb 2 | 14:00-14:20 | 20m | ao-implement |
| Feb 1 | 16:00-17:00 | 60m | ao-plan, ao-implement |
| Jan 31 | 10:00-10:15 | 15m | ao-validation |
| Jan 30 | 14:00-14:15 | 15m | ao-testing |
| Jan 28 | 14:00-14:05 | 5m | ao-plan |

## Time Distribution by Command
| Command | Time | % |
|---------|------|---|
| ao-implement | 100m | 69% |
| ao-plan | 25m | 17% |
| ao-testing | 15m | 10% |
| ao-validation | 5m | 4% |

## Issue Time Fields
| Field | Value |
|-------|-------|
| started_at | 2026-01-28 14:05 |
| completed_at | (not set) |
| duration_minutes | 145 |
```

### 4. Command View

Time spent by command/skill type.

```markdown
# Command Time Report

## By Command
| Command | Time | % | Sessions | Avg |
|---------|------|---|----------|-----|
| ao-implement | 2h 0m (120 min) | 50% | 6 | 20m |
| ao-plan | 1h 0m (60 min) | 25% | 3 | 20m |
| ao-validation | 30m | 13% | 2 | 15m |
| ao-testing | 30m | 12% | 1 | 30m |

**Total**: 4h 0m across 12 sessions
```

### 5. Sessions View

List of all tracked sessions.

```markdown
# Sessions Report

## Completed Sessions (12)

| Session | Date | Time | Duration | Commands | Issue |
|---------|------|------|----------|----------|-------|
| uuid-1 | Feb 2 | 18:00-18:30 | 30m | ao-implement | FEAT-0001@abc123 |
| uuid-2 | Feb 2 | 14:00-14:20 | 20m | ao-implement | FEAT-0001@abc123 |
| uuid-3 | Feb 1 | 16:00-17:00 | 60m | ao-plan, ao-implement | FEAT-0001@abc123 |
| uuid-4 | Jan 31 | 10:00-10:15 | 15m | ao-validation | FEAT-0001@abc123 |
| uuid-5 | Jan 30 | 14:00-14:30 | 30m | ao-testing | FEAT-0001@abc123 |
| uuid-6 | Jan 30 | 10:00-10:05 | 5m | ao-plan | FEAT-0001@abc123 |
| uuid-7 | Jan 29 | 15:00-15:35 | 35m | ao-implement | FEAT-0002@def456 |
| uuid-8 | Jan 29 | 11:00-11:20 | 20m | ao-implement | FEAT-0002@def456 |
| uuid-9 | Jan 28 | 16:00-16:20 | 20m | ao-plan | FEAT-0002@def456 |
| uuid-10 | Jan 28 | 14:00-14:10 | 10m | ao-implement | FEAT-0002@def456 |
| uuid-11 | Jan 27 | 10:00-10:10 | 10m | ao-validation | FEAT-0002@def456 |
| uuid-12 | Jan 27 | 09:00-09:05 | 5m | ao-plan | FEAT-0002@def456 |
```

### 6. Active View

Current active session details.

```markdown
# Active Session

| Field | Value |
|-------|-------|
| Session ID | uuid-current |
| Started | Feb 2, 2026 18:35 |
| Last Heartbeat | Feb 2, 2026 18:42 (7 min ago) |
| Duration (so far) | 7m |
| Command | ao-implement |

## Context
| Field | Value |
|-------|-------|
| Issue | FEAT-0001@abc123 |
| Epic | Authentication |
| Confidence | normal |
```

## Arguments

| Argument | Values | Default | Description |
|----------|--------|---------|-------------|
| `--view` | summary, epic, issue, command, sessions, active | summary | Report type |
| `--epic` | <string> | | Filter by epic name |
| `--issue` | <issue-id> | | Filter by issue ID |
| `--days` | <number> | 0 (all) | Last N days only |

## Example Invocations

```
# Summary report
Time report
→ Shows all time by epic, issue, command

# Epic breakdown
Time report --view epic --epic Authentication
→ All time for Authentication epic

# Issue details
Time report --view issue --issue FEAT-0001@abc123
→ Full time tracking for this issue

# Command breakdown
Time report --view command
→ Time spent by command type

# Session list
Time report --view sessions
→ All completed sessions

# Active session
Time report --view active
→ Current session status

# Last 7 days only
Time report --days 7
→ Summary of last week's work
```

## Time Formatting

Display times in human-readable format:
- `< 60 min`: Show as "Xm" (e.g., "35m")
- `>= 60 min`: Show as "Xh Ym" (e.g., "2h 25m")
- Also show raw minutes in parentheses: "(145 min)"

## Session Timeouts

When viewing sessions, note that:
- Sessions auto-end after 5 minutes of inactivity
- A gap >5 min between commands creates a new session
- This ensures accurate tracking of actual work time
