---
name: agent-ops-report
description: "Generate markdown reports from issues. Filter by type, priority, epic, date range. Supports summary, detailed, progress, completion, velocity, and backlog analysis views."
category: extended
invokes: [agent-ops-state, agent-ops-interview]
invoked_by: []
state_files:
  read: [issues/*.md]
  write: []
---

# Report Generation Skill

**Works with or without `aoc` CLI installed.** Report data can be gathered via direct file reading.

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

## Data Retrieval (File-Based — Default)

Reports are generated by reading issue files directly:

| Data Source | How to Retrieve |
|-------------|-----------------|
| All issues | Read `.agent/issues/{critical,high,medium,low}.md` |
| Completed issues | Read `.agent/issues/history.md` |
| Epic progress | Search for `epic:` field across priority files |
| Blocked issues | Search for `status: blocked` in priority files |

### File-Based Report Generation

1. **Summary Report**: Count issues in each priority file, group by type
2. **Completion Report**: Parse `history.md` for date ranges, group by type/epic
3. **Velocity Report**: Count issues by date from `### Log` entries
4. **Backlog Analysis**: Calculate age from `created:` field in each issue
5. **Epic Progress**: Filter issues by `epic:` field, calculate completion %

## CLI Integration (when aoc is available)

When `aoc` CLI is detected in `.agent/tools.json`, these commands provide convenience shortcuts:

| Command | Description | Example |
|---------|-------------|---------|
| `aoc issues summary` | Quick counts by priority | `aoc issues summary` |
| `aoc issues list` | List with filters | `aoc issues list --priority critical,high` |
| `aoc issues kanban` | Kanban board view | `aoc issues kanban --no-done` |
| `aoc issues show <ID>` | Single issue details | `aoc issues show FEAT-0001@abc123 --json` |

### Export for Reports (CLI)

```bash
# Export all open issues as JSON
aoc issues list --json > open-issues.json

# Export by priority for summary report
aoc issues list --priority critical --json
aoc issues list --priority high --json

# Export epic progress data
aoc issues list --epic "authentication" --json

# Include completed issues for history report
aoc issues list --done --json
```

## 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. 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%

## 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. 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:open,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/reports/{type}-{date}.md`
- **Clipboard**: Copy to clipboard for pasting

## Example Invocations

```
Generate a summary report
→ Summary with all open issues

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
```

## Integration with Other Skills

- **agent-ops-focus-scan**: Uses summary to identify next work
- **agent-ops-housekeeping**: Validates issues before reporting
- **agent-ops-tasks**: Shares issue parsing logic
- **agent-ops-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 `agent-ops-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)