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

Summary Report: Count issues in each priority file, group by type
Completion Report: Parse history.md for date ranges, group by type/epic
Velocity Report: Count issues by date from ### Log entries
Backlog Analysis: Calculate age from created: field in each issue
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:

Extract open questions from the issue
Invoke agent-ops-interview with questions as interview items
Update issue with answers after each question
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)

Search AI Tools

agent-ops-report

Install this agent skill to your Project

SKILL.md

Report Generation Skill

Goal

Data Retrieval (File-Based — Default)

File-Based Report Generation

CLI Integration (when aoc is available)

Export for Reports (CLI)

Report Types

1. Summary Report (default)

2. Completion Report (NEW)

3. Progress/Velocity Report (ENHANCED)

4. Backlog Analysis Report (NEW)

5. Session History Report (NEW)

6. Epic Progress Report

7. Detailed Report

Output Formats

JSON Output Schema

HTML Output

Filters

Output Options

Example Invocations

Integration with Other Skills

Automatic Handoff to Interview

Issues Needing Clarification

Handoff Behavior

Interview Handoff Procedure

Post-Interview Summary

Skip Conditions