Define OpenSpec change for monthly expense tracker v1

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

@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: User can record categorized expenses
+The system SHALL allow the user to create an expense with a title, amount, category, and local calendar date using fixed starter categories.
+
+#### Scenario: Valid expense is created
+- **WHEN** the user submits a title, positive amount, valid category, and valid local date
+- **THEN** the system stores the expense and returns the created record
+
+#### Scenario: Invalid expense is rejected
+- **WHEN** the user submits a missing title, invalid amount, invalid category, or invalid date
+- **THEN** the system rejects the request with a validation error and does not store the expense
+
+### Requirement: User can review and delete expenses
+The system SHALL allow the user to list recorded expenses and delete a specific expense by identifier.
+
+#### Scenario: Expenses are listed
+- **WHEN** the user requests expenses for the app
+- **THEN** the system returns stored expenses in a stable order with their recorded fields
+
+#### Scenario: Expense is deleted
+- **WHEN** the user deletes an existing expense
+- **THEN** the system removes that expense and it no longer appears in future listings or aggregates

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

@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: Dashboard shows month-specific financial totals
+The system SHALL return month-specific dashboard data for a requested `YYYY-MM` month using the local machine timezone for month boundaries.
+
+#### Scenario: Dashboard totals are calculated for a populated month
+- **WHEN** the user requests the dashboard for a month with expenses and paychecks
+- **THEN** the system returns total expenses, total paychecks, net cash flow, and a category breakdown for that month
+
+#### Scenario: Dashboard supports partial current-month data
+- **WHEN** the user requests the dashboard for the current month before the month is complete
+- **THEN** the system returns meaningful month-to-date totals and comparisons using the transactions recorded so far
+
+### Requirement: Dashboard includes derived spending comparisons
+The system SHALL provide derived comparisons for the selected month, including highest category, largest expense, average daily spend, and paycheck coverage information.
+
+#### Scenario: Derived comparisons are available
+- **WHEN** the selected month contains enough data for comparisons
+- **THEN** the system returns the highest category, largest single expense, average daily spend, and spend-versus-paycheck coverage values
+
+#### Scenario: Derived comparisons degrade safely for sparse data
+- **WHEN** the selected month has no expenses or otherwise insufficient data for a comparison
+- **THEN** the system returns null or empty-safe comparison fields instead of failing

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

@@ -0,0 +1,23 @@
+## 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

openspec/changes/monthly-expense-tracker-v1/specs/paycheck-tracking/spec.md

@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: User can record paychecks by pay date
+The system SHALL allow the user to create a paycheck with a positive amount and a local pay date.
+
+#### Scenario: Valid paycheck is created
+- **WHEN** the user submits a positive amount and valid local pay date
+- **THEN** the system stores the paycheck and returns the created record
+
+#### Scenario: Invalid paycheck is rejected
+- **WHEN** the user submits a missing or invalid amount or date
+- **THEN** the system rejects the request with a validation error and does not store the paycheck
+
+### Requirement: User can review and delete paychecks
+The system SHALL allow the user to list recorded paychecks and delete a specific paycheck by identifier.
+
+#### Scenario: Paychecks are listed
+- **WHEN** the user requests paychecks for the app
+- **THEN** the system returns stored paychecks in a stable order with their recorded fields
+
+#### Scenario: Paycheck is deleted
+- **WHEN** the user deletes an existing paycheck
+- **THEN** the system removes that paycheck and it no longer appears in future dashboard totals or insight inputs