From d132bfa238f812956f23d26049f869770bc16f22 Mon Sep 17 00:00:00 2001
From: Bill Ballou <bill@bballou.com>
Date: Fri, 24 Apr 2026 22:41:07 -0400
Subject: [PATCH] Add UUID lookup guidance: category/payee fields are UUIDs,
 not names

Jarvis was grep-ing transaction JSON for text like "swim" instead of
resolving the Swim Lessons category UUID first. Added:
- Warning that payee/category fields are UUIDs
- Two-step lookup patterns for category and payee searches
- Date range guidance: topic queries without dates search all-time
- Updated Groceries example with proper UUID filter
---
 SKILL.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 62 insertions(+), 3 deletions(-)

diff --git a/SKILL.md b/SKILL.md
index c9b2e42..17bb207 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -66,6 +66,61 @@ source "$(find ~/.claude -path '*/actual-budget/scripts/actual-helper.sh' 2>/dev
 
 All functions output JSON. Amounts are in decimal format (e.g., `123.45`), not Actual's internal integer format.
 
+## Important: Transaction Fields Use UUIDs
+
+Transaction `payee` and `category` fields are **UUIDs, not human-readable names**.
+You MUST cross-reference them with `actual_categories` and `actual_payees` to get names.
+
+**Never grep transaction JSON for category or payee names** — the names don't appear
+in the transaction records. Only `imported_payee` and `notes` contain free text, and
+these are unreliable (banks change formatting, Zelle shows generic "Zelle Transfer", etc.).
+
+### Searching by Category Name
+
+To find transactions in a category (e.g., "Swim Lessons"):
+
+```bash
+# Step 1: Get the category UUID
+source /home/node/.openclaw/workspaces/family-assistant/skills/finance/scripts/actual-helper.sh
+actual_categories  # Find: {"id": "c830de67-...", "name": "Swim Lessons", ...}
+
+# Step 2: Get transactions and filter by that UUID
+actual_transactions "" "2024-01-01" "$(date +%Y-%m-%d)" \
+  | python3 -c "
+import sys, json
+txns = json.load(sys.stdin)
+cat_id = 'c830de67-...'  # from step 1
+matches = [t for t in txns if t.get('category') == cat_id]
+print(json.dumps(matches, indent=2))
+"
+```
+
+### Searching by Payee Name
+
+To find transactions for a payee (e.g., "Aqua Warriors"):
+
+```bash
+# Step 1: Get the payee UUID
+actual_payees  # Find the payee by name
+
+# Step 2: Filter transactions by payee UUID
+actual_transactions "" "2024-01-01" "$(date +%Y-%m-%d)" \
+  | python3 -c "
+import sys, json
+txns = json.load(sys.stdin)
+payee_id = 'f26f8469-...'  # from step 1
+matches = [t for t in txns if t.get('payee') == payee_id]
+print(json.dumps(matches, indent=2))
+"
+```
+
+### Date Range for Topic-Specific Queries
+
+When the user asks about spending on a **specific topic** without specifying dates
+(e.g., "how much have we spent on swim lessons?"), search **all-time** (from 2024-01-01)
+rather than defaulting to the current month. Only use narrow date ranges when the user
+explicitly says "this month" or "in March".
+
 ## Common Query Patterns
 
 ### "How much did I spend this month?"
@@ -79,10 +134,14 @@ actual_accounts
 ```
 
 ### "Show me transactions for Groceries this month"
-First get categories to find the ID, then query transactions and filter:
+Two-step lookup — resolve category name to UUID, then filter:
 ```bash
-actual_categories  # find the category ID
-actual_transactions "" "$(date +%Y-%m)-01" "$(date +%Y-%m-%d)"  # then filter by category in the JSON output
+# Step 1: Get the category UUID from actual_categories output
+actual_categories  # find {"id": "abc123...", "name": "Groceries"}
+
+# Step 2: Filter transactions by that UUID
+actual_transactions "" "$(date +%Y-%m)-01" "$(date +%Y-%m-%d)" \
+  | python3 -c "import sys,json; txns=json.load(sys.stdin); [print(json.dumps(t)) for t in txns if t.get("category")=="abc123..."]"
 ```
 
 ### "Am I over budget this month?"