Report Generator

Overview

Aggregate data from multiple sources — activity logs, git history, and
user context — into structured, professional reports.

Core principle: Reports should be generated from evidence, not
memory. Every claim in a report traces back to a commit, an activity
record, or explicit user input.

Announce at start:

"Generating report — collecting data from activity logs and git
history."

When to Use

Manual triggers:

• "generate a weekly report" / "weekly status" / "週報"
• "create a monthly summary" / "月報"
• "project status report" / "專案報告"
• "sprint report" / "milestone report"
• "incident report" / "事故報告"
• "retrospective" / "retro" / "回顧"
• "summarize what I've been working on"

Prompted by other skills:

• After sp-finishing-a-development-branch — branch completion is a
  natural moment to capture what was accomplished
• After work-log-analyzer aggregation — formatted data is ready to
  become a report
• After accumulating 10+ activity-logger records without a report

Workflow

Phase 1: Determine Report Type and Scope

Ask the user (one question):

"What type of report do you need?
A) Weekly status (last 7 days)
B) Monthly summary (last 30 days)
C) Project summary (all time, current repo)
D) Sprint/Milestone (specific date range)
E) Incident report (specific event)
F) Retrospective (specific period)"

If the user's trigger phrase already implies the type (e.g., "weekly
report"), skip this question and confirm the scope:

"Generating weekly status report for the last 7 days. Correct?"

Phase 2: Collect Data

Run data collection in parallel where possible:

From activity-logger (if records exist):

bash ~/.claude/skills/activity-logger/scripts/init_activities.sh list
bash ~/.claude/skills/work-log-analyzer/scripts/aggregate_activities.sh \
  -m json -r <range>

From git history (current repo):

git log --oneline --since="<start-date>" --until="<end-date>"
git shortlog -sn --since="<start-date>" --until="<end-date>"
git diff --stat <start-commit>..HEAD

From user context (ask if needed):

• "Any highlights or blockers you want to call out?"
• "Who is the audience for this report?"

If a data source is unavailable (no activity records, not in a git
repo), skip it gracefully and note the gap in the report.

Phase 3: Generate Report

Apply the appropriate template based on report type. Each template
defines required sections — fill only sections that have supporting
data.

Common report header:

# [Report Type]: [Project/Period]

**Date**: YYYY-MM-DD
**Period**: YYYY-MM-DD to YYYY-MM-DD
**Author**: [user name or "Generated by Claude Code"]
**Project**: [project name from git or user input]

Phase 4: Review and Refine

Present the draft report to the user:

"Here's the draft. Want me to adjust anything — add detail, remove
sections, change tone, or reformat?"

Iterate until the user approves.

Phase 5: Save and Deliver

After approval:

1. Save to docs/reports/YYYY-MM-DD-<type>-<topic>.md
2. Commit with message: docs(reports): add <type> report for <period>
3. Offer format conversion (if needed):
   • "Want this as a DOCX? I can hand off to document-skills:docx"
   • "Want to present this? I can hand off to
     interactive-presentation-generator"

Report Templates

Weekly Status Report

# Weekly Status: [Project]

**Period**: YYYY-MM-DD to YYYY-MM-DD

## Summary
<!-- 2-3 sentence overview of the week -->

## Completed
<!-- From activity-logger: type=task_completed + git commits -->
- [Task description] ([commit hash])

## In Progress
<!-- From activity-logger: recent tasks without completion + git branches -->
- [Task description] — [current status]

## Blockers / Issues
<!-- From user input or activity-logger context -->
- [Blocker description] — [mitigation]

## Metrics
| Metric | Value |
|--------|-------|
| Commits | N |
| Files changed | N |
| Lines added | +N |
| Lines removed | -N |

## Next Week
<!-- From user input -->
- [Planned work]

Monthly Summary Report

# Monthly Summary: [Project]

**Period**: YYYY-MM to YYYY-MM

## Highlights
<!-- Top 3-5 accomplishments from activity-logger -->

## Work Breakdown
| Category | Count | Examples |
|----------|-------|---------|
| Features | N | [list] |
| Bug fixes | N | [list] |
| Refactoring | N | [list] |
| Documentation | N | [list] |

## Git Statistics
<!-- From git shortlog + diff --stat -->

## Key Decisions
<!-- From work-log-analyzer decision queries -->

## Lessons Learned
<!-- From user input -->

## Next Month Outlook
<!-- From user input -->

Project Summary Report

# Project Summary: [Project]

**Date**: YYYY-MM-DD
**Repository**: [git remote URL, sanitized]

## Project Overview
<!-- From README + CLAUDE.md + user input -->

## Architecture
<!-- From codebase structure analysis -->

## Development History
<!-- From git log, summarized by month/phase -->

## Current State
<!-- From git status + test results if available -->

## Team Contributions
<!-- From git shortlog -sn -->

## Open Issues / Technical Debt
<!-- From user input -->

Incident Report

# Incident Report: [Title]

**Date**: YYYY-MM-DD
**Severity**: [Critical / High / Medium / Low]
**Status**: [Resolved / Mitigated / Investigating]

## Timeline
| Time | Event |
|------|-------|
| HH:MM | [What happened] |

## Root Cause
<!-- From user input + git blame if applicable -->

## Impact
<!-- From user input -->

## Resolution
<!-- From git commits + user description -->

## Action Items
- [ ] [Preventive measure]

## Lessons Learned

Retrospective Report

# Retrospective: [Period/Sprint]

**Period**: YYYY-MM-DD to YYYY-MM-DD
**Participants**: [user input]

## What Went Well
<!-- From activity-logger: completed tasks + user input -->

## What Didn't Go Well
<!-- From user input + activity-logger: bug patterns -->

## What We Learned
<!-- From user input -->

## Action Items
- [ ] [Action] — Owner: [name] — Due: [date]

## Metrics Comparison
<!-- If previous retro exists, compare -->
| Metric | Previous | Current | Trend |
|--------|----------|---------|-------|

Examples

Example 1: Weekly Report

User: "generate a weekly report"

RIGHT:

"Generating report — collecting data from activity logs and git history."

1. Runs aggregate_activities.sh -m json -r this-week
2. Runs git log --oneline --since="7 days ago"
3. Finds 12 commits, 3 activity records
4. Asks: "Any blockers or highlights to add?"
5. Generates weekly status with Completed/In Progress/Metrics
6. Presents draft → user approves → saves to docs/reports/

WRONG:

Writes a report from memory without running any data collection
commands. Fabricates commit counts or file numbers.

Example 2: After Branch Completion

Prompted by sp-finishing-a-development-branch:

"Branch merged. Want to capture what was accomplished with
report-generator?"

User: "Sure, project summary"

RIGHT:

Collects full git history for the merged branch, activity records for
the period, and generates a project summary scoped to that feature.

Rationalization Prevention

Excuse	Reality
"I'll just write it from memory"	Memory is unreliable. Activity logs and git history are evidence. Use them.
"Nobody reads reports"	Reports create accountability and institutional memory. Future-you will thank present-you.
"The git log IS the report"	Git logs are raw data. Reports are curated narratives with context, priorities, and next steps.
"I'll do it later"	Reports degrade with time as context fades. Generate when the data is fresh.

Constraints

• Evidence-based only — every claim traces to a data source
• No fabricated metrics — if data is unavailable, say so
• User controls audience — adjust tone (technical vs. executive)
• Markdown first — generate Markdown, convert to other formats on
  request
• Reports are concise — weekly: max 1 page, monthly: max 2 pages,
  project: max 3 pages
• Save to docs/reports/ — consistent location for all reports
• Sanitize filenames — strip characters outside [a-z0-9-]

---

Error Handling

No Activity Records Found

• Fall back to git history as the primary data source
• Inform the user: "No activity-logger records found for this period.
  Report will be based on git history only."
• Suggest running activity-logger going forward

Not in a Git Repository

• Fall back to activity-logger records only
• If neither source is available, ask the user to provide content
  manually and act as a structured formatting tool

Date Range Produces No Data

• Inform the user: "No commits or activities found for [date range]."
• Suggest expanding the range or checking the repository

Conflicting Data Sources

• When activity-logger and git history disagree (e.g., different file
  counts), prefer git as the authoritative source and note the
  discrepancy

---

Security Considerations

Sensitive Information Filtering

• Strip git remote URLs that contain tokens or credentials before
  including in reports (remove user:token@ from URLs)
• Do not include file contents, only file paths and summary statistics
• Warn if activity-logger records contain tags like "credentials",
  "secret", or "api-key"

Report Distribution Safety

• Reports saved to docs/reports/ may be committed to the repo —
  remind the user if the repo is public
• Incident reports may contain sensitive timeline details — ask about
  audience before saving

File Path Safety

• Sanitize report filenames: strip characters outside [a-z0-9-]
• Validate docs/reports/ exists before writing; create if missing

---

Related Skills

• activity-logger — primary data source (structured activity records)
• work-log-analyzer — data aggregation layer (reads activity-logger output)
• code-story-teller — complementary narrative for specific files
• sp-finishing-a-development-branch — natural trigger point for reports
• document-skills:docx — optional DOCX format conversion
• document-skills:pdf — optional PDF format conversion
• interactive-presentation-generator — convert report to presentation