---
name: ao-report
description: "Generate markdown reports from issues. Filter by type, priority, epic, date range. Supports summary, detailed, progress, completion, velocity, and backlog analysis views. Configurable detail level and output style."
category: extended
invokes: [ao-state, ao-interview]
invoked_by: []
state_files:
  read: [issues/active.jsonl, issues/events.jsonl]
  write: []
arguments:
  - name: detail
    type: enum
    values: [low, normal, extensive]
    default: normal
    description: "Controls output depth: low=counts only, normal=summary+key issues, extensive=full breakdown"
  - name: style
    type: enum
    values: [technical, narration, formal]
    default: formal
    description: "Controls voice/tone: technical=terse, narration=conversational, formal=professional"
---

# Report Generation Skill

Report data is gathered via `ao` CLI commands from the JSONL event store.

## Goal
Generate informative reports from issue data to help users understand project status, prioritize work, analyze velocity, and review history. Supports multiple output formats, detail levels, output styles, and automatic clarification handoff.

## Arguments

### Detail Level (`--detail` or `-d`)

Controls how much information is included in the report.

| Level | Description | Use Case |
|-------|-------------|----------|
| `low` | Counts and high-level stats only | Quick status check, dashboards |
| `normal` | Summary + key issues listed (default) | Regular updates, standups |
| `extensive` | Full breakdown with descriptions, logs, timestamps | Detailed review, audits |

### Style (`--style` or `-s`)

Controls the voice and tone of the report output.

| Style | Description | Use Case |
|-------|-------------|----------|
| `technical` | Terse, data-focused, developer-oriented | Dev team updates, CLI output |
| `narration` | Conversational, storytelling format | Stakeholder updates, blog posts |
| `formal` | Professional, report-style (default) | Management reports, documentation |

### Behavior Matrix

| Detail × Style | Output Characteristics |
|----------------|------------------------|
| low + technical | "25 open, 12 crit, +7 vel" |
| low + formal | "Total: 25 open issues (12 critical)" |
| low + narration | "The project currently has 25 open issues..." |
| normal + technical | Stats + ID list, no prose |
| normal + formal | Executive summary + tables |
| normal + narration | "This week the team made progress on..." |
| extensive + technical | Full data dump, machine-readable |
| extensive + formal | Comprehensive report with all details |
| extensive + narration | Full narrative with context and history |

## Data Retrieval (ao CLI)

Reports are generated by querying the ao event store:

| Data Source | Command |
|-------------|----------|
| All open issues | `ao ls` |
| Completed issues | `ao ls --status done` |
| Issues by epic | `ao ls epic:<ID>` |
| Blocked issues | `ao ls --status blocked` |
| Backlog items | `ao ls priority:backlog` |
| Single issue detail | `ao --yes issue show <ID>` |

### Report Generation

1. **Summary Report**: `ao ls` — count by priority/type
2. **Completion Report**: `ao ls --status done` — filter by date, group by type/epic
3. **Velocity Report**: Count completions from events in `issues/events.jsonl` by date
4. **Backlog Analysis**: `ao ls` — calculate age from `created` field
5. **Epic Progress**: `ao ls epic:<ID>` — calculate completion %, sum `duration_minutes`
6. **Time Analysis**: Aggregate `duration_minutes` from `ao ls --status done`

### Time Aggregation (for Epic and Time Reports)

When generating time-aware reports, aggregate `duration_minutes` from completed issues:

```
FOR each issue WHERE status == 'done':
    IF duration_minutes exists AND > 0:
        total_time += duration_minutes
        epic_time[issue.epic] += duration_minutes
        type_time[issue.type] += duration_minutes
        confidence_time[issue.confidence] += duration_minutes

# Calculate averages
avg_per_issue = total_time / count(done_issues)

# Estimate remaining (for epics)
remaining_issues = count(todo + in_progress)
estimated_remaining = remaining_issues * avg_per_issue
```

## CLI Reference (ao commands)

Use `ao` to query issues for report generation:

| Command | Description | Example |
|---------|-------------|---------|
| `ao ls` | List open issues | `ao ls --sort priority` |
| `ao ls priority:critical` | Filter by priority | `ao ls priority:high` |
| `ao ls --status done` | Completed issues | `ao ls --status done` |
| `ao --yes issue show <ID>` | Single issue details | `ao --yes issue show FEAT-0001` |

### Query Examples for Reports

```bash
# All open issues
ao ls

# Filter by priority for summary report
ao ls priority:critical
ao ls priority:high

# Epic progress data
ao ls epic:FEAT-0010

# Completed issues for history report
ao ls --status done

# Backlog items
ao ls priority:backlog
```

## Report Types

### 1. Summary Report (default)
Quick overview of current state.

```markdown
# Project Status Report
Generated: 2026-01-15

## Open Issues by Priority
| Priority | Count | Types |
|----------|-------|-------|
| Critical | 2 | BUG(1), SEC(1) |
| High | 5 | FEAT(3), BUG(2) |
| Medium | 12 | FEAT(5), CHORE(4), DOCS(3) |
| Low | 8 | CHORE(5), DOCS(3) |

## Recent Activity (7 days)
- Created: 6 issues
- Completed: 4 issues
- Net change: +2

## Blocked Issues
- FEAT-0023@abc123 — blocked by BUG-0021@def456
```

### 2. Completion Report (NEW)
Issues completed in a time period, grouped by type and epic.

```markdown
# Completion Report
Period: 2026-01-01 to 2026-01-15

## Summary
- Total Completed: 24 issues
- By Type: FEAT(10), BUG(8), CHORE(4), DOCS(2)
- By Epic: Auth(8), Dashboard(6), API(5), Other(5)

## Completed by Type

### Features (10)
| ID | Title | Epic | Completed |
|----|-------|------|-----------|
| FEAT-0011 | Login form | Auth | Jan 12 |
| FEAT-0015 | Dashboard charts | Dashboard | Jan 14 |
...

### Bug Fixes (8)
| ID | Title | Priority | Completed |
|----|-------|----------|-----------|
| BUG-0023 | Session timeout | critical | Jan 10 |
| BUG-0027 | Button alignment | low | Jan 15 |
...

## Completed by Epic

### Auth Epic (FEAT-0010)
- FEAT-0011 — Login form (Jan 12)
- FEAT-0012 — Password reset (Jan 13)
- BUG-0023 — Session timeout (Jan 10)
...

### Dashboard Epic (FEAT-0020)
...

## Daily Breakdown
| Date | Count | Issues |
|------|-------|--------|
| Jan 15 | 3 | FEAT-0015, BUG-0027, CHORE-0031 |
| Jan 14 | 2 | FEAT-0014, DOCS-0030 |
...
```

### 3. Progress/Velocity Report (ENHANCED)
Track velocity trends and estimate completion.

```markdown
# Velocity Report
Generated: 2026-01-15

## Current Metrics
- Open Issues: 25
- In Progress: 4
- Blocked: 2
- Completed (last 7 days): 12
- Created (last 7 days): 5
- Net Throughput: +7

## Velocity Trend (Weekly)
| Week | Completed | Created | Net | Velocity/Day |
|------|-----------|---------|-----|--------------|
| Jan 13-19 | 12 | 5 | +7 | 1.7 |
| Jan 6-12 | 8 | 10 | -2 | 1.1 |
| Dec 30-Jan 5 | 5 | 15 | -10 | 0.7 |
| Dec 23-29 | 3 | 2 | +1 | 0.4 |

## Velocity Chart
```
        Completed   Created
Jan 13   ████████████  █████
Jan 6    ████████      ██████████
Dec 30   █████         ███████████████
Dec 23   ███           ██
```

## Projections (at current velocity)
- Days to clear backlog: ~15 days
- Issues per week: ~8.4
- Estimated zero-open: Feb 1, 2026

## Recommendations
- Velocity increasing: +50% over last 4 weeks ✅
- Backlog growing: +8 net issues → consider scope review
- High-priority focus: 2 critical issues still open → prioritize
```

### 4. Backlog Analysis Report (NEW)
Age distribution, stale items, and health metrics.

```markdown
# Backlog Analysis
Generated: 2026-01-15

## Age Distribution
| Age | Count | % of Total | Issues |
|-----|-------|------------|--------|
| < 7 days | 8 | 32% | Recent |
| 7-30 days | 10 | 40% | Active |
| 30-90 days | 5 | 20% | Aging |
| > 90 days | 2 | 8% | Stale |

## Stale Issues (>90 days old)
These haven't been touched and may need review:

| ID | Title | Created | Days Old | Priority |
|----|-------|---------|----------|----------|
| FEAT-0005 | Legacy API cleanup | Oct 1 | 106 | low |
| IDEA-0008 | Dark mode | Sep 15 | 122 | backlog |

**Recommendation**: Review stale issues — close, deprioritize, or reactivate.

## Priority Distribution
```
Critical: ██ 2 (8%)
High:     ██████████ 10 (40%)
Medium:   ████████ 8 (32%)
Low:      █████ 5 (20%)
```

## Type Distribution
```
FEAT:  ████████████████ 15 (60%)
BUG:   ████████ 6 (24%)
CHORE: ████ 3 (12%)
DOCS:  █ 1 (4%)
```

## Health Indicators
- ✅ No critical bugs > 7 days old
- ⚠️ 2 high-priority items > 14 days old
- ❌ 2 stale items need review
- ✅ Healthy type distribution
```

### 5. Confidence Statistics Report (NEW)
Track confidence-related outcomes and patterns.

```markdown
# Confidence Statistics
Period: Last 30 days

## Issues by Confidence Level
| Confidence | Completed | Regressions | Success Rate |
|------------|-----------|-------------|-------------|
| Low | 12 | 3 | 75.0% |
| Normal | 25 | 2 | 92.0% |
| High | 18 | 0 | 100.0% |

## Confidence vs Outcome Analysis
- Low confidence issues with regressions: BUG-0023, FEAT-0056, REFAC-0078
- High confidence issues re-opened: none ✅
- Confidence mismatches (marked high but regressed): none ✅

## Recommendations
- ✅ Low confidence controls working: 3 issues caught by mandatory review
- ⚠️ Consider raising validation tier for REFAC issues (2 regressions from same type)
- ✅ High confidence accuracy: 100% — quickfix path reliable
```

### 6. Session History Report (NEW)
What was accomplished in recent agent sessions.

```markdown
# Session History
Last 5 sessions

## Session: 2026-01-15 (Today)
Duration: ~2 hours
Branch: main
Commits: 3

### Completed
- ✅ ENH-0153 — Extend housekeeping skill to split issue files
- ✅ ENH-0163 — Auto-archive completed issues
- ✅ ENH-0154 — Update all skills for split files

### Created
- IDEA-0167 — New onboarding flow

### In Progress
- IDEA-0145 — Web UI documentation

---

## Session: 2026-01-14
Duration: ~3 hours
Branch: feature/api-improvements

### Completed
- ✅ BUG-0142 — Fix API timeout
- ✅ FEAT-0140 — Add pagination

### Blocked
- FEAT-0141 — OAuth (waiting on credentials)

---
(More sessions...)
```

### 6. Epic Progress Report
Track progress on a specific epic.

```markdown
# Epic Progress: FEAT-0010@xyz789 — User Authentication

## Status
- Total issues: 8
- Completed: 3 (37.5%)
- In Progress: 2
- Blocked: 1
- Remaining: 2

## Progress Bar
[████████░░░░░░░░░░░░] 37.5%

## Time Tracking
| Metric | Value |
|--------|-------|
| Total Time Spent | 145 min (2h 25m) |
| Avg per Issue (done) | 48 min |
| Estimated Remaining | ~290 min (6 × 48 avg) |
| Projected Total | ~435 min (~7h 15m) |

## Time Distribution
- FEAT issues: 110 min (76%)
- TEST issues: 0 min (0%)
- CHORE issues: 35 min (24%)

## Issues
| ID | Title | Status | Effort |
|----|-------|--------|--------|
| ✅ FEAT-0011@... | Login form | done | S |
| ✅ FEAT-0012@... | Password reset | done | M |
| ✅ TEST-0015@... | Auth unit tests | done | S |
| 🔄 FEAT-0013@... | OAuth integration | in-progress | L |
| 🔄 FEAT-0014@... | Session management | in-progress | M |
| ⛔ SEC-0002@... | Input validation | blocked | M |
| ⬚ DOCS-0016@... | Auth documentation | open | S |
| ⬚ TEST-0017@... | Integration tests | open | M |
```

### 7. Time Analysis Report
Analyze time spent across epics or time periods.

```markdown
# Time Analysis Report

## Summary (Last 7 Days)
| Metric | Value |
|--------|-------|
| Total Time Tracked | 485 min (8h 5m) |
| Issues Completed | 12 |
| Avg per Issue | 40.4 min |

## By Epic
| Epic | Issues | Total Time | Avg |
|------|--------|------------|-----|
| GATS-7386 | 3 | 145 min | 48 min |
| Auth-Refactor | 5 | 210 min | 42 min |
| Tech-Debt | 4 | 130 min | 33 min |

## By Type
| Type | Count | Total | Avg |
|------|-------|-------|-----|
| FEAT | 6 | 280 min | 47 min |
| BUG | 3 | 95 min | 32 min |
| TEST | 2 | 70 min | 35 min |
| CHORE | 1 | 40 min | 40 min |

## By Confidence
| Confidence | Count | Total | Avg |
|------------|-------|-------|-----|
| high | 8 | 240 min | 30 min |
| normal | 3 | 180 min | 60 min |
| low | 1 | 65 min | 65 min |

## Velocity Trend
| Week | Issues | Time | Avg |
|------|--------|------|-----|
| 2026-W04 | 5 | 200 min | 40 min |
| 2026-W05 | 7 | 285 min | 41 min |
```

### 8. Detailed Report
Full listing with descriptions.

```markdown
# Detailed Issue Report

## Critical (P0)
### BUG-0001@abc123 — Login timeout crashes app
- **Created**: 2026-01-10
- **Epic**: FEAT-0010@xyz789
- **Effort**: M
- **Description**: Users experience crash after 30s idle...
```

## Output Formats

Reports support multiple output formats:

| Format | Flag | Description |
|--------|------|-------------|
| Markdown | `--format md` (default) | Rich markdown with tables |
| JSON | `--format json` | Structured data for processing |
| Plain Text | `--format text` | Simple text, no formatting |
| HTML | `--format html` | Standalone HTML page |

### JSON Output Schema

```json
{
  "report_type": "summary",
  "generated": "2026-01-15T10:30:00Z",
  "filters": {"priority": ["critical", "high"]},
  "data": {
    "total_open": 25,
    "by_priority": {"critical": 2, "high": 5, ...},
    "by_status": {"todo": 15, "in_progress": 4, ...},
    "issues": [...]
  }
}
```

### HTML Output

Generates a standalone HTML file with:
- Embedded CSS (no external dependencies)
- Collapsible sections
- Sortable tables
- Print-friendly styling

## Filters

Reports can be filtered by:

| Filter | Syntax | Example |
|--------|--------|---------|
| Type | `type:TYPE` | `type:BUG`, `type:FEAT,SEC` |
| Priority | `priority:LEVEL` | `priority:critical,high` |
| Epic | `epic:ID` | `epic:FEAT-0010@xyz789` |
| Status | `status:STATUS` | `status:todo,in_progress` |
| Date range | `from:DATE to:DATE` | `from:2026-01-01 to:2026-01-15` |
| Label | `label:NAME` | `label:api,backend` |
| Effort | `effort:SIZE` | `effort:l,xl` |

## Output Options

- **Console** (default): Display in chat
- **File**: Write to `.agent/ops/reports/{type}-{date}.md`
- **Clipboard**: Copy to clipboard for pasting

## Example Invocations

### Basic Reports

```
Generate a summary report
→ Summary with all open issues (default: normal detail, formal style)

Generate completion report from:2026-01-01
→ All issues completed since Jan 1

Generate velocity report
→ Velocity trends and projections

Generate backlog analysis
→ Age distribution and stale items

Generate session history
→ What was done in recent sessions

Generate epic progress for FEAT-0010@xyz789
→ Epic progress report for that epic

Generate completion report type:BUG --format json
→ Completed bugs as JSON
```

### With Detail Level

```
Generate report --detail low
→ Quick stats: "25 open, 12 critical, +7 velocity"

Generate report --detail normal
→ Standard report with executive summary (default)

Generate report --detail extensive
→ Full breakdown with all descriptions, logs, timestamps
```

### With Style

```
Generate report --style technical
→ Terse output: "crit:2 high:5 med:12 low:8 | +7/wk"

Generate report --style formal
→ Professional report format (default)

Generate report --style narration
→ "Over the past week, the team closed 15 issues..."
```

### Combined Arguments

```
Generate report --detail low --style technical
→ "25 open, 12 crit, +7 vel"

Generate report --detail normal --style formal
→ Standard executive summary with tables

Generate report --detail extensive --style narration
→ "The project began in January with a focus on authentication.
   Over the first week, the team completed 15 issues including..."

Generate velocity report --detail extensive --style technical
→ Full velocity data in dense, developer-friendly format
```

## Integration with Other Skills

- **ao-focus-scan**: Uses summary to identify next work
- **ao-housekeeping**: Validates issues before reporting
- **ao-task**: Shares issue parsing logic
- **ao-interview**: Handoff for issues needing clarification

---

## Automatic Handoff to Interview

After generating a report, scan for issues needing clarification and offer to resolve them.

### Issues Needing Clarification

Detect issues with:
- Open questions (unchecked `- [ ]` items in "Questions to Resolve" section)
- Status: `needs-context`, `draft`, `clarify`
- Type: `PLAN` with incomplete acceptance criteria
- Missing required fields (no scope, no acceptance criteria)
- Confidence: `low` without explicit rationale
- Blocked status without clear blocker

### Handoff Behavior

After displaying the report:

```markdown
---

## 🔍 Issues Needing Clarification

| ID | Title | Reason |
|----|-------|--------|
| PLAN-0001@a7f3c2 | Issue Viewer Requirements | 7 open questions |
| FEAT-0023@def456 | OAuth Integration | Missing acceptance criteria |
| BUG-0015@ghi789 | Login timeout | Needs reproduction steps |

**Start clarification interview?**
1. PLAN-0001@a7f3c2 (7 questions)
2. FEAT-0023@def456 (2 questions)
3. BUG-0015@ghi789 (1 question)
4. All issues sequentially
5. Skip for now

Choice [1-5]:
```

### Interview Handoff Procedure

When user selects an issue:

1. **Extract open questions** from the issue
2. **Invoke `ao-interview`** with questions as interview items
3. **Update issue** with answers after each question
4. **Return to report** when interview complete

Example flow:
```
User: 1

Starting interview for PLAN-0001@a7f3c2...

Question 1 of 7:
What platform/technology should the Issue Viewer use?
- Web app (cross-platform, easy deploy)
- VS Code extension (native integration)
- Electron (desktop native)
- CLI TUI (lightweight, terminal)
- Other?

Your choice:
```

### Post-Interview Summary

After completing clarification:

```markdown
✅ Interview Complete: PLAN-0001@a7f3c2

Resolved:
- [x] Platform: VS Code extension
- [x] Read/write: Read-only initially
- [x] Views: List + Kanban
- [x] Filters: By priority, type, epic

Remaining:
- [ ] Integration with external trackers
- [ ] Offline support
- [ ] Team features

Issue updated. Continue with next issue or return to report?
```

### Skip Conditions

Don't offer interview handoff if:
- Report type is `history` (completed issues don't need clarification)
- All issues are fully specified
- User passed `--no-interview` flag
- Report is output to file only (`--file` without console)

