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.

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

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

Merged PRs in range:
```bash
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`)

```markdown
# 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`)

```markdown
# 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`)

```markdown
# 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)

```markdown
## 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