financial-manager-expert

name	Financial-Manager-Expert
description	Specialist in the Financial Management module, handling transaction tracking, SMS automated logging, categories, and financial reporting.

Financial Manager Expert

Use this skill when modifying the financial dashboard, category management, transaction editor, or SMS auto-sync.

1. SMS Auto-Import Pipeline

• Decoupled Architecture: SMS logic is separated into SmsParser (pure stateless regex text extraction) and SmsService (listener, notification dispatcher, and database transactions).
• Centralized Regexes: All bank regexes, credit/debit keywords, and sender IDs must reside in sms_constants.dart.
• SMS Deduplication: Skip logs if another identical transaction occurred within $\pm5$ minutes (cross-sender/duplicate check).
• Automatic Reversals: Refund or reversal messages delete the matching target transaction within a 7-day window using the __reversal__ sentinel.
• Pre-Filtering & AI Parsing: Use isPotentiallyRelevant filters (check amounts, keywords) to skip OTPs/cancellations before calling Gemini Nano. The AI parser must return clean merchant name, category, and direction (income vs expense) in one JSON payload.
• Periodic Duration-Based Background Sync: Use Workmanager().registerPeriodicTask for interval syncs (e.g., every 12 hours) to comply with Android Doze mode battery rules. For 24-hour daily sync, expose a conditional Auto-Sync Time picker and schedule initial delay using calculateDailySyncDelay(timeStr).

2. Category & Keyword Rules

• Case-Insensitive Validation: Validate category names case-insensitively when creating/editing to avoid duplicate naming collisions.
• Double-Level Matching: Keywords match merchant names. Multi-word keywords (e.g. "Keells Super") take precedence over single-word keywords (e.g. "Keells") using cached matches.
• Inline Calculator: Support mathematical operators (+, -, *, /) directly inside the amount field via CalculatorDialog.

3. Home Screen Widget & Deep Linking

• Android PendingIntent Re-use: The Android OS caches PendingIntents using the destination Component and requestCode as keys. If deep link intent parameters (like custom action strings or extras) are modified, you MUST assign a new unique requestCode in the Kotlin widget provider to force the OS to invalidate its cache. Otherwise, the old intent action is run.
• Startup Synchronization: To prevent widgets from getting out-of-sync with Dart storage on app launch, call WidgetHelper.updateWidgetData() inside the App Home Screen's initState() to force update the widget's PendingIntents and shared states.

4. Recurring Transactions & Widget Analytics (v2.0)

• Recurring rules: recurring_rules table + RecurringRuleRepository.materializeDueRules() — idempotent, capped catch-up loop (36 periods max), advances nextDue with month-length clamping. Called at the top of the finance dashboard refresh; the transaction editor creates the rule only for NEW transactions ("Once/Daily/Weekly/Monthly" SegmentedButton); manage/delete via the sheet in Settings → Financial Manager. Ledger is the first/default tab.
• Widget analytics tiers: Dart (WidgetHelper) computes and writes prefs (spent today/month, NET + sign, budget % from summed categoryBudgets, top category); Kotlin renders by OPTION_APPWIDGET_MIN_HEIGHT tiers — stats always, budget bar ≥120dp (only when budgets exist), top category next, recent transactions ONLY ≥260dp. Use NumberFormat('#,##0') for thousands separators.
• Widget freshness: updatePeriodMillis=1800000 redraws from prefs every ~30min; a 4h WorkManager task (kWidgetRefreshTaskName) recomputes prefs so TODAY rolls over at midnight. The task MUST keep its initialDelay (cold-start SQLCipher deadlock — see Tester skill).

5. Category Management & Custom Icons (v2.3)

• Cascading Category Renaming: Renaming a category must execute cascading SQLite updates across both transactions (UPDATE transactions SET category = ... WHERE category = ...) and recurring_transactions (UPDATE recurring_rules SET category = ... WHERE category = ...).
• Custom Icon Persistence: Store category icons as integer iconCodePoint in SQLite. Resolve icon displays using TransactionCategory.iconFor(name) with a const Map<int, IconData> lookup map to satisfy Flutter release tree-shaking rules.
• Safe Category Deletion: Non-'Other' categories can be deleted; always execute an automatic reassignment query updating past transactions and recurring rules to 'Other' before dropping the category definition. 'Other' must remain protected from deletion.

6. On-Device Trend Forecasting & Robust Regression (v2.7)

• Exponentially-Weighted Linear Regression: Models spending trends using recency weights $w_i = \gamma^{n - 1 - i}$.
• Huber-Style Outlier Dampening: Detects single spending anomalies ($Z > 1.8\sigma$) and reduces their regression weight by 75% so one-off spikes don't distort future predictions. Displays a 🛡️ Outlier Dampened badge on the visual card when active.
• On-Device Self-Tuning Model: Evaluates optimal decay factor $\gamma \in [0.70 \dots 0.95]$ dynamically on local transaction history using Leave-One-Out cross-validation.