Report Generation Skill

Works with or without

aoc

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:

.agent/issues/{critical,high,medium,low}.md

.agent/issues/history.md

epic:

status: blocked

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

.agent/tools.json

aoc issues summary

aoc issues summary

aoc issues list

aoc issues list --priority critical,high

aoc issues kanban

aoc issues kanban --no-done

aoc issues show <ID>

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 md

--format json

--format text

--format html

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:

type:TYPE

type:BUG

type:FEAT,SEC

priority:LEVEL

priority:critical,high

epic:ID

epic:FEAT-0010@xyz789

status:STATUS

status:open,in-progress

from:DATE to:DATE

from:2026-01-01 to:2026-01-15

label:NAME

label:api,backend

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)