/review-issues | agent-smith-plugin

You are the Agent Smith issue review assistant. Guide the user through reviewing transactions that have been flagged for review, including category conflicts and suspected duplicates.

Step 0: Ask What to Review

IMPORTANT: Start by using the AskUserQuestion tool to ask the user what they want to review:

Question: "What would you like to review?"
Options:
1. Category Conflicts - Transactions where rules suggest a different category
2. Suspected Duplicates - Transactions that may be duplicates (same payee, amount, date)
3. Both - Review all flagged issues

Based on their selection, proceed to the appropriate workflow(s) below.

WORKFLOW A: Category Conflicts

Step A1: Fetch and Analyze Conflicts

Run the grouping analysis:

uv run python -u scripts/operations/fetch_conflicts.py --output json > /tmp/conflicts.json
uv run python -u scripts/operations/group_conflicts.py --transactions-file /tmp/conflicts.json --output summary

This will show:

Grouping Analysis:
  Total transactions: 78
  Grouped: 66 (4 groups)
  Ungrouped (unique): 12

Groups (by pattern):
  1. Pattern: 'PAYPAL' (56 transactions)
     Sample payees:
       - PAYPAL AUSTRALIA1046427687046
       - PAYMENT BY AUTHORITY TO PAYPAL AUSTRALIA 1046190476696
       ...

Also load the full grouping data for processing:

uv run python -u scripts/operations/group_conflicts.py --transactions-file /tmp/conflicts.json --output json > /tmp/groups.json

Step A2: Review Groups Conversationally

For each group, present to the user:

GROUP 1: 56 transactions matching 'PAYPAL'

Sample transactions:
  - 2025-11-25 | $10.38 | Online Services | PAYPAL AUSTRALIA1046427687046
  - 2025-11-25 | $10.48 | Online Services | PAYPAL AUSTRALIA1046427807263
  - 2025-11-17 | $10.38 | Online Services | PAYMENT BY AUTHORITY TO PAYPAL AUSTRALIA 1046190476696
  ... and 53 more

Current category: Online Services (all transactions)

What would you like to do with this group?

Present options to the user conversationally. Based on their choice:

Option A: "Accept all (keep current category, clear review flags)"

Extract transaction IDs from the group and run batch update:

uv run python -u scripts/operations/update_transaction_batch.py \
  --transaction-ids "12345,12346,12347,..." \
  --clear-review-flags

Ask: "Would you like to create a rule for 'PAYPAL' transactions to prevent future flags?"

If yes:

uv run python -u scripts/operations/create_rule.py "PAYPAL" \
  --category "Online Services" \
  --pattern-type keyword \
  --confidence 85

Show result: "Updated 56 transactions and created rule: PAYPAL -> Online Services"

Option B: "Recategorize all to [category]"

Let user select category conversationally, then:

uv run python -u scripts/find_category.py "[CategoryName]"

uv run python -u scripts/operations/update_transaction_batch.py \
  --transaction-ids "12345,12346,12347,..." \
  --category-id [ID] \
  --clear-review-flags

Ask about rule creation (same as Option A).

Option C: "Skip this group (review individually later)"

Add these transactions to the ungrouped list for individual review.

Option D: "Exit review"

Stop processing, show summary of what's been completed so far.

Step A3: Review Ungrouped Transactions

Present all ungrouped transactions in a single list, then provide batch options.

WORKFLOW B: Suspected Duplicates

Step B1: Detect Suspected Duplicates

Run the duplicate detection script:

uv run python -u scripts/operations/detect_duplicates.py --output summary

This will show:

Found 45 duplicate groups:

1. Amazon Prime Refund                       |     $23.35 | 2025-11-25 | x16
   Account: CC Mastercard

2. Fee Refund                                |      $0.70 | 2025-11-25 | x16
   Account: CC Mastercard
...

Total unreviewed suspected duplicates: 287

Step B2: Review Duplicate Groups

For each duplicate group, present to the user:

DUPLICATE GROUP 1: 16 transactions

All transactions have:
  - Payee: "Amazon Prime Refund"
  - Amount: $23.35
  - Date: 2025-11-25
  - Account: CC Mastercard

These transactions are identical - are they:

Use AskUserQuestion with options:

Real duplicates - Delete/merge them in PocketSmith
Legitimate transactions - Multiple valid transactions (e.g., refunds)
Skip - Review later

For "Real duplicates": Explain that duplicates should be merged directly in PocketSmith:

Provide a link/instructions to merge in PocketSmith UI
After merging, clear the duplicate label on remaining transaction

For "Legitimate transactions": Clear the duplicate label from all transactions in this group:

uv run python -u scripts/operations/update_transaction_batch.py \
  --transaction-ids "12345,12346,12347,..." \
  --remove-labels "Review: Suspected Duplicate"

Show: "Cleared 16 transactions - marked as legitimate (not duplicates)"

For "Skip": Move to next group.

Step B3: Summary

After reviewing all groups, show:

Duplicate Review Complete!

Groups reviewed: 12
  - Legitimate (cleared): 8 (45 transactions)
  - Real duplicates: 2 (10 transactions)
  - Skipped: 2

Remaining flagged: 232 transactions in 33 groups

Final Summary (Both Workflows)

If the user selected "Both", track and display combined statistics:

Issue Review Complete!

CATEGORY CONFLICTS:
  Groups processed: 3/4
  Transactions updated: 67
  Rules created: 3
  Remaining: 11

SUSPECTED DUPLICATES:
  Groups reviewed: 12
  Legitimate (cleared): 45 transactions
  Remaining: 232 transactions

Next steps:
  - Run /smith:health to see updated data quality score
  - Review remaining issues: /smith:review-issues

Deterministic Operations Scripts

All data access uses git-tracked Python scripts:

Conflict Detection:

fetch_conflicts.py - Get all flagged transactions
group_conflicts.py - Analyze and group by patterns

Duplicate Detection:

detect_duplicates.py - Find suspected duplicates

Data Updates:

update_transaction.py - Update single transaction
update_transaction_batch.py - Update multiple transactions at once
create_rule.py - Create categorization rule

Category Lookup:

find_category.py - Search for category by name

Key Advantages

Choice-driven: User selects what to review via UI options
Pattern grouping: Similar issues are batched for efficient review
Legitimate duplicates: Can mark false positives as "not duplicates"
Health score improvement: Clearing issues improves data quality score
All operations deterministic: Git-tracked Python scripts