smith-report

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.

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.

2. Print in chat — Display the full report.

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