gsd-session-report

name: gsd-session-report description: "Generate a session report with token usage estimates, work summary, and outcomes" allowed-tools:

• Read
• Bash
• Write

<required_reading> Read the skill content below before starting. </required_reading>

1. STATE.md — current phase, milestone, progress, blockers, decisions
2. Git log — commits made during this session (last 24h or since last report)
3. Plan/Summary files — plans executed, summaries written
4. ROADMAP.md — milestone context and phase goals

# Get recent commits (last 24 hours)
git log --oneline --since="24 hours ago" --no-merges 2>/dev/null || echo "No recent commits"

# Count files changed
git diff --stat HEAD~10 HEAD 2>/dev/null | tail -1 || echo "No diff available"

Read .planning/STATE.md to get:

• Current milestone and phase
• Progress percentage
• Active blockers
• Recent decisions

Read .planning/ROADMAP.md to get milestone name and goals.

Check for existing reports:

ls -la .planning/reports/SESSION_REPORT*.md 2>/dev/null || echo "No previous reports"

• Count of tool calls is not directly available, so estimate from git activity and file operations
• Note: This is an estimate — exact token counts require API-level instrumentation not available to hooks

Estimation heuristics:

• Each commit ≈ 1 plan cycle (research + plan + execute + verify)
• Each plan file ≈ 2,000-5,000 tokens of agent context
• Each summary file ≈ 1,000-2,000 tokens generated
• Subagent spawns multiply by ~1.5x per agent type used </step>

mkdir -p .planning/reports

Write .planning/reports/SESSION_REPORT.md (or .planning/reports/YYYYMMDD-session-report.md if previous reports exist):

# GSD Session Report

**Generated:** [timestamp]
**Project:** [from PROJECT.md title or directory name]
**Milestone:** [N] — [milestone name from ROADMAP.md]

---

## Session Summary

**Duration:** [estimated from first to last commit timestamp, or "Single session"]
**Phase Progress:** [from STATE.md]
**Plans Executed:** [count of summaries written this session]
**Commits Made:** [count from git log]

## Work Performed

### Phases Touched
[List phases worked on with brief description of what was done]

### Key Outcomes
[Bullet list of concrete deliverables: files created, features implemented, bugs fixed]

### Decisions Made
[From STATE.md decisions table, if any were added this session]

## Files Changed

[Summary of files modified, created, deleted — from git diff stat]

## Blockers & Open Items

[Active blockers from STATE.md]
[Any TODO items created during session]

## Estimated Resource Usage

| Metric | Estimate |
|--------|----------|
| Commits | [N] |
| Files changed | [N] |
| Plans executed | [N] |
| Subagents spawned | [estimated] |

> **Note:** Token and cost estimates require API-level instrumentation.
> These metrics reflect observable session activity only.

---

*Generated by `/gsd-session-report`*

## Session Report Generated

📄 `.planning/reports/[filename].md`

### Highlights
- **Commits:** [N]
- **Files changed:** [N]  
- **Phase progress:** [X]%
- **Plans executed:** [N]

If this is the first report, mention:

💡 Run `/gsd-session-report` at the end of each session to build a history of project activity.

<success_criteria>

• Session data gathered from STATE.md, git log, and plan files
• Report written to .planning/reports/
• Report includes work summary, outcomes, and file changes
• Filename includes date to prevent overwrites
• Result summary displayed to user </success_criteria>