---
name: period-report
description: Generate monthly / quarterly / yearly spend rollups with category breakdown, top merchants, project profitability, and budget variance. Owned by the accountant.
allowed-tools: generate_finance_report query_finance query_budget
title: Period Report
category: finance
status: active
metadata:
  triggers:
  - monthly report
  - quarterly report
  - yearly report
  - spending summary
  - show me the month
  - tax report
  - deductible summary
  priority: 5
  model_tier: capable
  language:
    output_policy: source
---
## What this skill is

Phase 3-equivalent surface for the accountant — generates structured spend rollups for arbitrary periods. Output is markdown saved to `agntspace-finance/reports/` with proper file authorship (`author: agent`, `agent: accountant`, `date: <today>`).

This skill is the slow, narrated cousin of `budget-track`. Use this when the user asks for "the report" — a comprehensive document. Use `budget-track` for fast structured budget questions.

## When to use

- Monthly / quarterly / yearly cron triggers (1st of period).
- User explicitly requests: "Generate my April report" or "Tax-deductible summary for 2026".
- After EOD when the user has approved a significant batch of transactions and asks for a recap.

## Flow

1. Identify the period (calendar month / quarter / year, or explicit YYYY-MM / YYYY-Qn / YYYY).
2. Filter transactions: `status=verified`, `txn_date` in period.
3. Aggregate by:
   - **Category** — total spend per category, sorted desc
   - **Merchant** — top 10 by spend
   - **Project** — per-project spend; flag projects whose spend exceeds their tracked budget
   - **Currency** — multi-currency totals (no FX conversion — show natively per Phase 2.2 layer 1)
4. Compute budget variance: for each budget covering this period, `actual / cap` and call out exceedances.
5. Compute tax-deductible total when `deductible_only=true`.
6. Write the report markdown to `agntspace-finance/reports/{period}-overview.md` with the canonical frontmatter.

## Rules
- NEVER fabricate transactions, amounts, merchants, or categories. Every claim must trace to a specific `txn_id`. The report's "Top merchants" section is a list of REAL transactions.
- NEVER convert currencies — show them natively side-by-side. FX conversion is Phase 2.2 layer 2.
- NEVER mark transactions tax-deductible from this skill — surface candidates only, the user owns that flag.
- NEVER mix data across vaults. Per-vault data isolation per Rule #1.
- ALWAYS cite txn_ids when reporting specific transactions; aggregate prose without underlying line-item evidence is forbidden.

## Output format

The report markdown:

```markdown
---
title: "Spend report — {period}"
author: agent
agent: accountant
date: {today}
period: {period}
generated_at: {ISO}
---

# Spend Report — {period}

## Summary

Total spend: {total_native_currency}
Transaction count: {n}
Budget variance: {N on track, M near cap, P over}

## By category

| Category | Spend | Transactions |
|---|---|---|
| {cat} | {amount} | {n} |
...

## Top merchants

1. {merchant} — {amount} ({n} transactions)
...

## Project rollup

| Project | Spend | Budget | Variance |
|---|---|---|---|

## Notable items

- {txn_id}: {description}
```

End with a one-line summary in plain prose: "April spending up 12% vs March, driven mostly by AI infra (+$143)."

## Examples

User: "Show me my March report."

Output: a `reports/2026-03-overview.md` file with the structure above, plus a chat-side acknowledgment: "Report saved to agntspace-finance/reports/2026-03-overview.md. {1-line summary}."