AGENTS/.pi/gsd/workflows/session-report.md

<gsd-version v="1.12.4" />

<gsd-execute>
  <display msg="Loading session context..." />
  <shell command="pi-gsd-tools">
    <args>
      <arg string="state" />
      <arg string="json" />
      <arg string="--raw" />
    </args>
    <outs>
      <suppress-errors />
      <out type="string" name="state" />
    </outs>
  </shell>
  <shell command="pi-gsd-tools">
    <args>
      <arg string="current-timestamp" />
      <arg string="--raw" />
    </args>
    <outs>
      <out type="string" name="timestamp" />
    </outs>
  </shell>
  <shell command="pi-gsd-tools">
    <args>
      <arg string="roadmap" />
      <arg string="analyze" />
      <arg string="--raw" />
    </args>
    <outs>
      <suppress-errors />
      <out type="string" name="roadmap" />
    </outs>
  </shell>
</gsd-execute>

## Session Context (pre-injected by WXP)

**Generated:** <gsd-paste name="timestamp" />

**State:**
<gsd-paste name="state" />

**Roadmap:**
<gsd-paste name="roadmap" />

---

<purpose>
Generate a post-session summary document capturing work performed, outcomes achieved, and estimated resource usage. Writes SESSION_REPORT.md to .planning/reports/ for human review and stakeholder sharing.
</purpose>

<required_reading>
Read all files referenced by the invoking prompt's execution_context before starting.
</required_reading>

<process>

<step name="gather_session_data">
Collect session data from available sources:

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

```bash
# 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:
```bash
ls -la .planning/reports/SESSION_REPORT*.md 2>/dev/null || echo "No previous reports"
```
</step>

<step name="estimate_usage">
Estimate token usage from observable signals:

- 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>

<step name="generate_report">
Create the report directory and file:

```bash
mkdir -p .planning/reports
```

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

```markdown
# 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`*
```
</step>

<step name="display_result">
Show the user:

```
## 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.
```
</step>

</process>

<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>