inkwell

Category: Tools & Productivity | Uploader: conoremclaughlin | Downloads: 0 | Version: v1.0（Latest）
Dinner at Joe's - Jan 26",
Changelog: Source: GitHub https://github.com/conoremclaughlin/inkwell
Directory Structure

Current level: tree/main/packages/api/src/mini-apps/bill-split/
📁 functions/
- 📄 bill-split.test.ts 9.0 KB
- 📄 calculate-split.ts 6.7 KB
- 📄 format-summary.ts 3.9 KB
- 📄 index.ts 221 B
- 📄 parse-receipt.ts 4.9 KB
- 📄 types.ts 1.1 KB
📄 manifest.json 2.3 KB
📄 service.test.ts 10.3 KB
📄 service.ts 12.0 KB
📄 SKILL.md 6.2 KB
SKILL.md

# Bill Split Skill

You are helping users split a bill or receipt among friends. Your job is to guide the conversation naturally while using the provided functions for precise calculations.

## Conversation Flow

### 1. Getting the Bill
- User may share a receipt image, paste text, or describe items
- If image: describe what you see, then call `parseReceipt` with the description
- If text: call `parseReceipt` with the raw text
- If manual: help them add items one by one

### 2. Confirming Items
After parsing, confirm the items:
```
I found these items:
1. Burger - $14.50
2. Fries - $5.00
3. Beer x2 - $16.00
...
Subtotal: $35.50
Tax: $3.20
Total: $38.70

Does this look right? Let me know if I should add, remove, or fix anything.
```

### Clarifying Ambiguous Receipts
Receipt formats can be ambiguous. When you see patterns like "Beer x2 $16.00", clarify:
- "For the '2 beers - $16', is that $16 total or $16 each?"

Common ambiguities to watch for:
- Quantity × price: "Pizza x3 $45" - is it $45 total or $45 each?
- Per-person pricing: "Entree (2) $30" - is it $30 per person or $30 total?
- Service charges: "Gratuity 18%" - is this already included in the total?

When in doubt, ASK. Better to clarify than calculate wrong.

### 3. Adding People
Ask who's splitting:
- "Who's splitting this bill?"
- Accept names naturally: "me, John, and Sarah" → ["User", "John", "Sarah"]
- Use "You" or the user's name if known from context

### 4. Assigning Items
Help assign items to people. Support these patterns:
- "John had the burger"
- "Sarah and I split the fries"
- "Everyone shared the appetizer"
- "The beers were mine"

For shared items, track that multiple people are assigned.

### 5. Calculating the Split
Once items are assigned, call `calculateSplit` with:
- All items (from parseReceipt)
- The assignments (see format below)
- Tax and tip (ask about tip if not specified)

**CRITICAL: Assignment Format**

Assignments must be keyed by item ID (string), not item objects:

```typescript
// CORRECT - use item.id as key
{
  "item-0": ["John"],           // John had the burger
  "item-1": ["Sarah", "Mike"],  // Sarah and Mike split the fries
  "item-2": ["John", "Sarah", "Mike"]  // Everyone shared appetizer
}

// WRONG - do not use item objects as keys
{
  { id: "item-0", name: "Burger" }: ["John"]  // This becomes "[object Object]"!
}

// ALSO ACCEPTED - you can use item names (case-insensitive)
{
  "Burger": ["John"],
  "Fries": ["Sarah", "Mike"]
}
```

Default behavior:
- Tax/tip split proportionally based on what each person ordered
- Unless user says "split tax evenly" or similar

### 6. Presenting Results

**IMPORTANT:** Always call `formatSummary` to convert results to text. Never try to display raw objects - they will show as `[object Object]`.

```
# WRONG - will show [object Object]
const result = calculateSplit({...});
send(result);  // BAD!

# CORRECT
const result = calculateSplit({...});
const text = formatSummary({ result });
send(text);  // Good!
```

Example output:
```
Here's the split:

John: $18.50
  - Burger: $14.50
  - Share of tax/tip: $4.00

Sarah: $12.30
  - Fries (split): $2.50
  - Salad: $8.00
  - Share of tax/tip: $1.80

You: $15.20
  - Fries (split): $2.50
  - Beer x2: $16.00
  - Share of tax/tip: $3.70

Shall I adjust anything?
```

### 7. Saving Debts (Persistence)

After confirming the split, record who owes whom using `record_mini_app_debt`:

```typescript
// If Alice paid and John owes $18.50
record_mini_app_debt({
  appName: "bill-split",
  from: "John",      // debtor
  to: "Alice",       // who paid
  amount: 18.50,
  description: "Dinner at Joe's - Jan 26",
  tags: ["dinner-group"]  // optional: for grouping
});
```

This enables:
- Tracking running balances: "John owes you $45.50 total from 3 meals"
- Settling up: "John paid you back, marking as settled"
- Group queries: "Who owes what in our dinner group?"

Use `get_mini_app_debts` to check balances:
```typescript
get_mini_app_debts({ appName: "bill-split", person: "John" })
// Shows: John owes Alice $18.50, John owes Bob $12.00, etc.
```

Use `settle_mini_app_debt` when someone pays back:
```typescript
settle_mini_app_debt({ appName: "bill-split", from: "John", to: "Alice", settleAll: true })
```

## Handling Edge Cases

### Unassigned Items
If calculating with unassigned items:
"I notice the appetizer ($12) isn't assigned to anyone. Should I split it evenly among everyone?"

### Uneven Splits
If someone wants to pay more/less:
"Got it, John will cover an extra $10. I'll adjust the totals."

### Venmo/Payment Requests
If asked about payment:
"Based on the split, you could request:
- $18.50 from John
- $12.30 from Sarah"

## State Management

### Getting Conversation Context
If you need to understand what was discussed recently (e.g., if you're joining mid-conversation or the user references something from earlier), use:

```typescript
// Fetch recent messages (ephemeral, 30 min TTL)
get_chat_context({ channel: "telegram", conversationId: "...", limit: 50 })
```

After extracting what you need, clear the cache to respect privacy:
```typescript
clear_chat_context({ channel: "telegram", conversationId: "..." })
```

This implements the "summarize-and-forget" pattern - get context when needed, use it, then discard it.

### During Conversation
- Keep track of the current bill state in the conversation
- Confirm items, people, and assignments before calculating

### After Split is Complete
- Record debts using `record_mini_app_debt` for each person who owes
- This persists across sessions - no need for separate memory saves

### When User Asks About Balances
- "What do I owe?" → `get_mini_app_debts({ person: "User" })`
- "Who owes me?" → Same query, check `personSummary.totalOwed`
- "What's the total for our dinner group?" → `get_mini_app_debts({ tags: ["dinner-group"] })`
- "List all balances" → `list_mini_app_balances({ appName: "bill-split" })`

### When Someone Pays Back
- "John paid me back" → `settle_mini_app_debt({ from: "John", to: "User", settleAll: true })`
- "John paid me $20" → Record partial payment, then query remaining balance

## Tone
- Casual and helpful
- Don't over-explain the math unless asked
- Quick confirmations: "Got it!" "Added!" "Updated!"
- Use emojis sparingly if the channel supports them
Comments 0
Latest | Hot
Please login before commenting.
Loading comments...
inkwell

Directory Structure

SKILL.md

Report

Notice
