version: "1.0.1" name: smith-report description: Generate client-facing project reports from vault data — progress updates, decision logs, spec changelogs, or full audit reports. argument-hint: "[--range week|month|YYYY-MM-DD:YYYY-MM-DD] [--type progress|decisions|specs|full] [--project <name>]"

Smith Client Report Generator

Generate polished, client-facing project reports by synthesizing vault session logs, git history, spec artifacts, and audit results into a professional narrative.

Arguments: $ARGUMENTS

Vault Logging

Throughout this action, log significant events to the vault session log. Read the session log path from .smith/vault/.current-session. If the file is missing or the vault is not initialized, skip all logging silently.

Timestamps are UTC. HH:MM:SS comes from date -u +%H:%M:%S — never a local clock, never a time from memory. The append already runs through a shell, so read the clock in that same command (TS=$(date -u +%H:%M:%S)) and spend no extra tool call. Substitute the resulting value: an unexpanded $(...) reaching the log is a known regression and will not parse. Every hook-written stamp in this log is date -u, so a local-clock entry lands hours away from its neighbours and skews the workflow window hooks/workflow_summary_lib.py derives from them.

Append entries using this format:

### [HH:MM:SS] /smith-report <event>
 
**User Request:**
> <verbatim user message that triggered this action>
 
**Synthesized Input:** <brief summary>
**Outcome:** <what happened>
**Artifacts:** <files created>
**Systems affected:** <system IDs>

Log at these points:

1. On invocation — date range, report type, project
2. After generation — path to output file, report summary

Step 1: Gather Parameters

If $ARGUMENTS contains flags, parse them. Otherwise prompt for each missing parameter in a single message:

Date range (required):

• week — past 7 days
• month — past 30 days
• YYYY-MM-DD:YYYY-MM-DD — custom range

Report type (required):

• progress — what was built, what's in progress, what's next
• decisions — key decisions made and their reasoning
• specs — which specs were created, modified, or completed
• full — combines all of the above

Project (optional, defaults to current working directory):

• Read from ~/.smith/projects.json if multiple projects registered

Step 2: Gather Data

2.1 Vault Session Logs

Read all session logs from .smith/vault/sessions/ within the date range. Extract:

• Action invocations (/smith-* entries) with their input/outcome summaries
• Decisions logged (any **Outcome:**, **Answer:**, or question-answer pairs)
• File change counts per session
• Session durations

2.2 Git History

git log --since="<start>" --until="<end + 1 day>" --format="%ad | %H | %s" --date=short --no-merges --reverse

Merged PRs in range:

gh pr list --state merged --search "merged:>=<start> merged:<=<end>" --json number,title,mergedAt,body --limit 100

2.3 Spec Artifacts

Scan .specify/systems/*/features/ and specs/ for:

• Feature specs created in the date range (by created frontmatter or file modification date)
• Feature specs with status: complete updated in the range
• Spec modifications (git log of spec files)

2.4 Audit Results (for full report type)

Check specs/audits/ and vault session logs for audit findings logged within the date range.

2.5 Ledger Data (if .smith/vault/ledger/ exists)

1. Read meta.yaml for overview stats
2. Count entries per file and confidence level
3. Extract top 3 high-confidence patterns
4. Note any reflections that occurred within the reporting period
5. If Ledger is missing or empty, omit the Learning section from the report

Step 3: Generate Report

Use an LLM pass to transform raw vault data into polished narrative prose. The report should read as a professional project update suitable for sending directly to a client or stakeholder.

Progress Report (progress)

# Project Report: [Project Name]
**Period:** [Start Date] – [End Date]
**Generated:** [Today's Date]
 
## Executive Summary
 
[2-3 sentences summarizing the overall direction and key accomplishments of the period.]
 
## Work Completed
 
### [System or Feature Area]
[2-4 sentences describing what was built, why it matters, and the user-visible outcome.]
 
### [System or Feature Area]
[...]
 
## In Progress
 
-**[Feature]** — [brief status and expected completion]
-[...]
 
## Key Decisions
 
| Decision | Rationale | Impact |
|----------|-----------|--------|
| [What was decided] | [Why] | [What it affects] |
 
## Next Steps
 
-[What's planned for the next period]
-[...]
 
---
*Generated by Smith from vault session data and git history.*

Decision Log (decisions)

# Decision Log: [Project Name]
**Period:** [Start Date] – [End Date]
 
## Decisions Made
 
### [Date] — [Decision Topic]
**Context:** [What prompted this decision]
**Options considered:** [Brief list]
**Decision:** [What was chosen]
**Rationale:** [Why]
**Affected systems:** [Which systems were impacted]
 
### [Date] — [Decision Topic]
[...]
 
---
*Extracted from vault session logs and spec clarification records.*

Spec Changelog (specs)

# Spec Changelog: [Project Name]
**Period:** [Start Date] – [End Date]
 
## Features Completed
| Feature | System | PR | Completed |
|---------|--------|----|-----------|
| [Name] | [System] | #N | [Date] |
 
## Features In Progress
| Feature | System | Status | Branch |
|---------|--------|--------|--------|
| [Name] | [System] | [Phase] | [branch] |
 
## Specs Created
-**[Feature spec]** — [one-line description]
 
## Specs Modified
-**[Feature spec]** — [what changed and why]
 
---
*Generated from .specify/systems/ and git history.*

Full Report (full)

Combines all three sections above into a single comprehensive document, plus:

• An audit summary section (if audits were run in the period)
• A metrics section with: total commits, PRs merged, specs completed, estimated hours (from vault session data)
• A Learning & Patterns section (if Ledger data is available — see 2.5)

## Learning & Patterns
 
### Top Patterns (High Confidence)
-[Pattern title] — [brief description] ([N] observations)
 
### Recent Lessons
-[Date] — [lesson extracted from reflection]
 
### Ledger Health
| File | Entries | High | Medium | Low |
|------|---------|------|--------|-----|
| patterns.md | N | N | N | N |
| antipatterns.md | N | N | N | N |
| tool-preferences.md | N | N | N | N |
| edge-cases.md | N | N | N | N |
| project-quirks.md | N | N | N | N |

Step 4: Save & Present

1. Save to file — Write to .smith/vault/reports/report-<start>-to-<end>-<type>.md

• If file exists, append counter: -2, -3, etc.

1. Print in chat — Display the full report.

1. Offer follow-up:

`` Saved to .smith/vault/reports/<filename> Would you like me to adjust the tone, add more detail to a section, or generate a different report type? ``

Writing Guidelines

• Write as a professional project manager, not as an AI
• Use active voice and concrete outcomes ("Built X" not "X was implemented")
• No engineering jargon in progress reports (same rules as client timesheet audience)
• Decision logs can be more technical since they document reasoning
• Keep the executive summary under 100 words
• Group related work by system/feature area, not by date
• If a period had no activity, say so clearly rather than padding