agent-ops-report

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	utility
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)

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

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

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

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

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

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

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

# 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

{
  "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:

---

## 🔍 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:

✅ 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)