monthlytracker/openspec/changes/monthly-expense-tracker-v1/specs/monthly-insights/spec.md

ADDED Requirements

Requirement: User can generate monthly AI insights on demand

The system SHALL allow the user to manually generate AI insights for any month with existing or sparse data by sending structured monthly context to the configured OpenAI provider.

Scenario: Insights are generated for a month with data

• WHEN the user requests insight generation for a month with recorded activity
• THEN the system sends monthly aggregates plus transaction samples to the AI service and returns a rendered narrative summary with structured supporting totals

Scenario: Prior month insights can be generated

• WHEN the user requests insight generation for a previous month that has recorded data
• THEN the system generates and stores insight output for that requested month

Requirement: Insight generation is read-only and safe for sparse months

The system SHALL keep AI insight generation read-only and return a safe fallback summary when a month does not have enough data for meaningful guidance.

Scenario: Sparse month returns fallback insight

• WHEN the user requests insight generation for a month with empty or near-empty data
• THEN the system returns a fallback message instead of low-confidence advice

Scenario: AI does not mutate financial records

• WHEN the system generates or stores monthly insights
• THEN no expense or paycheck records are created, updated, or deleted as part of that request