tres-data-collection-commit

# Tres Finance — Data Collection (Commit)

## Overview

Commit is the step that pulls on-chain data into Tres Finance for the wallets
already onboarded to the org. It runs the platform's data-collection pipeline for
each wallet and either:

- **Full data collection** — collects the full transaction history *and* current
  balances. Used for a complete onboarding or historical backfill.
- **Balances only** — collects only the current asset balances (no transactions).
  Much faster; useful when the user just wants an up-to-date snapshot or is
  preparing for a quick balance validation.

This skill is the **second step** of the customer onboarding flow:

1. **Upload wallets** (`tres-wallets-upload`) — register the wallets in Tres.
2. **Collect data (this skill)** — run the commit so Tres actually fetches the
   on-chain state.
3. **Validate balances** (`tres-asset-balance-validation`) — cross-check the
   collected balances against DeBank.

## When to Use

Trigger this skill whenever the user wants to:

- Run a commit / trigger a commit / kick off data collection
- Collect on-chain data into Tres
- Pull balances or transactions for their wallets
- Sync wallets that were just added
- Refresh Tres data after adding new wallets

**Example phrases that must trigger this skill:**

- *"Run the commit"* / *"Trigger the commit"*
- *"Collect the data for my wallets"*
- *"Pull balances for everything"*
- *"I just added wallets — now collect the data"*
- *"Sync my wallets"*
- *"Start the data collection"*

---

## Prerequisites

| Requirement | Details |
|---|---|
| TRES Finance MCP connected | The TRES MCP tools (`get_viewer`, `execute`, `build_query`, `introspect`) must be available |
| Authenticated org | `get_viewer` must succeed and return an `orgName` |
| At least one wallet onboarded | If there are no wallets, commit has nothing to collect — point the user to `tres-wallets-upload` first |

---

## Process Overview

Follow these steps in order. Do **not** skip the user-selection steps — the
whole point of this skill is to capture the user's collection intent before
firing the mutation.

### Step 1 — Confirm authentication

Call `get_viewer` to verify the user is authenticated to Tres and note the
`orgName`. Mention it in the confirmation summary later so the user knows which
org the commit will run against.

If `get_viewer` fails: tell the user the TRES MCP is not connected and ask them
to connect it before continuing.

### Step 2 — Ask: full data or balances only?

This is the core choice of the skill. Ask the user **exactly** this (using the
`AskUserQuestion` tool if available, otherwise plain text):

> **What do you want to collect?**
>
> 1. **Full data collection** — collects all transactions and current balances.
>    Slower, but produces a complete ledger. Use this for first-time onboarding
>    or historical backfill.
> 2. **Balances only** — collects only current balances, no transactions. Fast.
>    Use this when you just want an up-to-date balance snapshot (for example,
>    before running balance validation).

Map the answer to the GraphQL parameter `balancesOnly`:

| User choice | `balancesOnly` |
|---|---|
| Full data collection | `false` |
| Balances only | `true` |

If the user is unsure, recommend **Full data collection** as the default for
first-time onboarding (because skipping transactions means the ledger will be
empty even after commit succeeds).

### Step 3 — Ask: all wallets, or specific wallets?

Ask the user whether the commit should run on every wallet or a subset:

> **Which wallets should I collect data for?**
>
> 1. **All wallets** — run the commit across every wallet in the org.
> 2. **Specific wallets** — only collect data for wallets I pick.

If the user chooses **All wallets**: set `internalAccountIds = null` (omit the
field in the mutation variables, or pass `null`).

If the user chooses **Specific wallets**:

1. Fetch the list of wallets from Tres so the user can pick from real options:
   ```graphql
   query ListWalletsForCommit {
     internalAccount {
       totalCount
       results {
         id
         name
         identifier
         parentPlatform
       }
     }
   }
   ```
2. Present the wallets as a numbered plain-text list (name + short address +
   platform). If there are more than ~25 wallets, show the first 25 and tell
   the user they can reply with wallet names, addresses, or IDs to narrow down.
3. Let the user respond conversationally ("the three Ethereum ones", "Treasury
   Hot and Cold Storage", "IDs 123, 456, 789", etc.). Resolve their response to
   a list of internal account `id` values. Never call the mutation with an
   unresolved name — always resolve to IDs first.
4. If you cannot confidently resolve a wallet the user named, ask them to
   clarify instead of guessing.

### Step 4 — Confirm before firing the mutation

Show a short plain-text summary of exactly what is about to happen and ask for
explicit confirmation. Example:

```
About to trigger a Commit in Tres Finance:

  Org:       Acme Labs
  Mode:      Full data collection (transactions + balances)
  Wallets:   All wallets in the org

Shall I run it now?
```

Or, for a scoped run:

```
About to trigger a Commit in Tres Finance:

  Org:       Acme Labs
  Mode:      Balances only
  Wallets:   3 selected
             - Treasury Hot (0x1887...3Cdd, ETHEREUM)
             - Cold Storage (bc1q...xyz, BITCOIN)
             - Ops Main (0x89Ba...92a8, POLYGON)

Shall I run it now?
```

Wait for an affirmative reply (`yes`, `confirm`, `go ahead`). Anything else:
treat as "not yet" and ask what to change.

### Step 5 — Trigger the commit

Run the `triggerCommit` mutation via the TRES MCP `execute` tool:

```graphql
mutation TriggerCommit(
  $balancesOnly: Boolean
  $internalAccountIds: [ID]
) {
  triggerCommit(
    balancesOnly: $balancesOnly
    internalAccountIds: $internalAccountIds
  ) {
    status
    message
    commitId
  }
}
```

Variable mapping:

| Variable | Value |
|---|---