| name | project-report |
| description | Generate a project report summarizing project progress for a given time period (month, quarter, or year-to-date). Gathers data from plan/history, git log, and GitHub PRs, then produces a capability-focused narrative with an executive summary and section headings. Use when the user asks for a project report, sponsor update, or monthly/quarterly summary — e.g. "/project-report May 2026" or "/project-report Q1 2026".
|
Skill: Project Report
Quick start
/project-report <period>
Examples: April 2026, May 2026, Q1 2026, Q2 2026, 2026
Workflow
Phase 1 — Parse the time period
Compute the date range and output path. The output folder is always the
YYMM of the end date (capped at today for open-ended periods):
| Input | Date range | Output YYMM |
|---|
April 2026 | 2026-04-01 – 2026-04-30 | 2604 |
May 2026 | 2026-05-01 – 2026-05-31 | 2605 |
Q1 2026 | 2026-01-01 – 2026-03-31 | 2603 |
Q2 2026 | 2026-04-01 – 2026-06-30 | 2606 |
Q3 2026 | 2026-07-01 – 2026-09-30 | 2609 |
Q4 2026 | 2026-10-01 – 2026-12-31 | 2612 |
2026 (full year, run in May) | 2026-01-01 – 2026-05-15 | 2605 |
Output path:
plan/history/<YYMM>/report/project-report-<YYYYMMDD>-<YYYYMMDD>.md
Example: plan/history/2604/report/project-report-20260401-20260430.md
If the file already exists, overwrite silently (reports are regenerable).
Report files are exempt from history immutability rules.
Phase 2 — Gather data in parallel
Run all of these simultaneously:
-
Git log — commits merged within the date range:
git log --oneline --after=<start_date> --until=<end_date> \
--merges --pretty=format:"%h %s"
-
GitHub PRs — all PRs merged during the period:
gh pr list --repo CERTCC/Vultron \
--state merged \
--json number,title,mergedAt,body \
--jq '[.[] | select(.mergedAt >= "<start_date>T00:00:00Z"
and .mergedAt <= "<end_date>T23:59:59Z")]'
-
History entries — read the plan/history/<YYMM>/ folder(s) that
overlap the period. For multi-month periods, read each relevant YYMM
folder's index and entry files. Focus on implementation/, priority/,
and learning/ subdirectories; skip report/ entries.
Phase 3 — Analyze and group
Review the gathered data against the theme heuristics in
REFERENCE.md.
- Map each significant PR and history entry to one of the theme categories
(e.g., Protocol automation, Multi-actor scenarios, API / architecture,
Developer tooling, Bug fixes, Documentation, Dependencies).
- Identify the 4–7 most prominent themes of the period.
- Skip or aggregate trivial changes (single-line fixes, routine bumps).
- Plan a single aggregate sentence for dependency-only PRs — do not list
them individually.
- Note any significant work that started but did not finish in the period;
flag those with an "in progress" caveat.
Phase 4 — Draft the report
Write the full report following the structure and tone guidelines in
REFERENCE.md:
- Frontmatter:
title, type, period_start, period_end, timestamp
- Executive summary: 2–4 sentences covering overall productivity, the
2–4 major themes, and any notable caveats
- Theme sections (4–7): one H2 heading per theme; lead with the
user-visible capability or outcome; link significant PRs inline using
[PR #NNN](https://github.com/CERTCC/Vultron/pull/NNN)
- Footer line:
*Report covers: <start> through <end> | Repository: [CERTCC/Vultron](https://github.com/CERTCC/Vultron)*
Hold the draft in memory — do not write to the output path yet.
Phase 5 — Review with user
Use ask_user to present the draft. Offer:
["Looks good — write it out", "I have feedback"]
If the user selects "I have feedback", incorporate the feedback and ask again.
Phase 6 — Write to file
Write the approved report to the path computed in Phase 1.
Prepend YAML frontmatter:
---
title: "<Period> Project Report"
type: report
period_start: "<YYYY-MM-DD>"
period_end: "<YYYY-MM-DD>"
timestamp: "<generation ISO datetime>"
---
