ramp-complete-expenses

Files (1)

• SKILL.md

SKILL.md (first lines)

## Non-Negotiables

- **Pass `--rationale` on every command** — it is a required field on these agent-tools (a non-empty string, max 1024 chars). With `--json`, supply it as a `"rationale"` key in the body. Omitting it returns `HTTP 422 (DEVELOPER_INVALID_SCHEMA)`, in both agent and human modes.
- Scope to the user's own transactions by default (`--transactions_to_retrieve my_transactions`) unless they explicitly request broader access.
- Only the acting cardholder can complete a transaction revision. Do not attempt
  revision completion as an admin, manager, or copilot on the cardholder's behalf.
- Show the transaction details before editing. Never blind-edit.
- Never upload a receipt without confirming the match — wrong receipt on wrong transaction is worse than no receipt.
- For bulk edits or receipt sweeps, present the plan and confirm before executing.
- Use `ramp transactions missing {uuid}` as the reliable check for whether a receipt is attached — it returns `missing_receipt: true/false` in real time. The `receipt_uuids` field in the list response can be used as a quick filter, but it may be stale (e.g., remaining null even after a successful upload+attach).
- CLI receipt uploads must be base64-encoded; accepted types are PNG, JPEG, PDF, HEIC, and WEBP.
- On MCP, never paste file contents or base64 into a tool call. Pick one path:
  - Chat app that shows an upload card (e.g. claude.ai): call `open-receipt-uploader`, even if the user already attached the file in chat — chat attachments can't reach Ramp.
  - Terminal agent with the file on disk (Claude Code, Cursor, Codex): call `request-receipt-upload-link` and run the returned `curl` (Step 6).
  - Neither: ask the user to upload in the Ramp web or mobile app, or email it to `receipts@ramp.com`.
- The `--user_submitted_fields` flag tracks provenance — include it to mark which fields the user explicitly provided vs agent-inferred.
- All CLI flags use **underscores**, not hyphens (e.g., `--from_date`, `--transaction_uuid`).

## `--rationale` is required

Every command in this skill maps to an agent-tool endpoint that **requires** a
`rationale`: a non-empty string (max 1024 chars) explaining why you are making
the call. Pass it as `--rationale "..."`, or include a `"rationale"` key in the
`--json` body. It is required for **both** agent (`--agent`) and human
(`agent=false`) invocations — omitting it is the #1 cause of `HTTP 422` errors on
these tools. The examples below all include it; keep it on every call.

## Workflow

### Revision-request tasks

When `GetAttentionFeed` / `ramp tasks list` returns
`TRANSACTION_REVISION_REQUESTED`, preserve the task's transaction UUID and
revision request context. Inspect the live transaction, show the requested
changes, and get the cardholder's explicit confirmation before editing.

1. Fix every requested agent-editable field with the applicable workflow below.
   A successful field edit does not itself complete the revision request.
2. Re-read the transaction and its missing items. If a requested field still
   needs user-only work, give the user the returned Ramp link and stop; do not
   complete the revision prematurely.
3. Ask the cardholder for, or have them approve, a nonblank completion reason
   summarizing how the request was resolved.
4. Complete the revision for that same transaction.

MCP:

```text
CompleteTransactionRevision(
  transaction_uuid="{transaction_uuid}",
  reason="Added the requested receipt and corrected the department",
  rationale="Complete the cardholder's resolved transaction revision"
)
```

CLI:

```bash
ramp transactions complete-revision {transaction_uuid} \
  --reason "Added the requested receipt and corrected the department" \
  --rationale "Complete the cardholder's resolved transaction revision" --agent
```

Treat the success response's sanction-lift status `PENDING_VERIFICATION` as an
instruction to verify, not as evidence that a card is unlocked. Poll
`GetAttentionFeed` / `ramp tasks list` and `ListCards` with a finite bound (at
most three rechecks in the current run). On every attention-feed attempt, follow
every section's cursor chain until `next_cursor` is null and require the number
of unique hydrated task UUIDs to equal each section's `total_count`; otherwise
the attempt is incomplete and cannot prove the revision task is absent. If a
section's `total_count` changes between pages, restart that bounded attempt from
the first page rather than combining two snapshots. Success requires a fully
accounted feed in which the same revision task has disappeared
and the exact sanctioned card reports `is_spendable: true`. If the bound is
exhausted, report the live task, `active_locks`, and `blocking_task_count`; do
not say the revision restored card spending.

If revision completion returns:

- `CompleteTransactionRevisionNotFoundError`, re-check the transaction UUID
  from the task context.
- `CompleteTransactionRevisionPermissionDeniedError`, stop and explain that the
  acting cardholder must complete their own revision.
- `CompleteTransactionRevisionFailedPreconditionError`, re-read the attention
  feed and transaction state. This also covers a replay after the revision is
  already complete; do not retry it as a new completion event.
- `CompleteTransactionRevisionInternalError`, report that completion could not
  be verified and leave the task outstanding.

### Step 1: Find transactions needing attention

```bash
ramp transactions list --transactions_to_retrieve my_transactions \
  --from_date {start} --state cleared --rationale "Find transactions needing cleanup" --agent --page_size 50
```

For any transaction, check what's missing:

```bash
ramp transactions missing {transaction_uuid} --rationale "Check missing items on the transaction"
```

Returns `missing_receipt` (bool), `missing_memo` (bool), and `missing_accounting_items` (an array of objects, not category-name strings). Each object has this shape:

```json
{
  "category_name": "QuickBooks Online Department",
  "category_id": "category-uuid"
}
```

Present results grouped by what's missing:

```
Needs attention: 8 transactions ($4,520 total)

  Missing receipts (3):
    $1,200  United Airlines     2026-03-01
    $  800  Hilton Hotels       2026-03-03

From ramp-public/skills, MIT.

More from ramp-public/skills