tres-cost-basis

# TRES Finance — Cost Basis Management

End-to-end skill for managing cost basis calculation, strategy configuration,
reevaluations, financial issue review, and related operations in TRES Finance.

---

## MCP Server

All calls use the `user-tres-finance` MCP server (the TRES Finance MCP connector).

All variable keys and nested input fields MUST use **camelCase** (e.g. `assetClassId`, not `asset_class_id`).

---

## Step 1 — Authenticate and confirm org

Call `get_viewer` with no arguments. Confirm the org name with the user if there
is any ambiguity.

---

## Step 2 — Ensure a cost basis strategy is defined (gate before calculation)

Before any cost basis calculation can run, the organization must have a strategy
defined. This step is a **prerequisite gate** — run it automatically whenever the
user wants to calculate cost basis (Section D), or when they first ask for help
with cost basis.

1. Fetch the current strategy using the query in Section B.
2. If `defaultStrategy` is returned (any valid value like FIFO, LIFO, etc.),
   the strategy is already set — **skip ahead** and inform the user:
   > "Your cost basis strategy is set to [STRATEGY]. Proceeding."
3. If no strategy is configured (the query returns null or an error), present
   the user with all available methods and ask them to choose:

   > "Before calculating cost basis, you need to choose a costing method.
   > Here are the available strategies:
   >
   > 1. **FIFO** — First-in, first-out. Earliest acquired lots are disposed first. The most common method.
   > 2. **LIFO** — Last-in, first-out. Most recently acquired lots are disposed first.
   > 3. **AVG** — Weighted average cost across all lots.
   > 4. **MAX_GAINS** — Disposes lowest-cost lots first, maximizing realized gains.
   > 5. **MAX_LOSSES** — Disposes highest-cost lots first, maximizing realized losses (useful for tax-loss harvesting).
   > 6. **FIFO_IMPAIRMENT** — FIFO with impairment accounting support (for orgs using impairment write-downs).
   >
   > Which method would you like to use?"

4. Once the user picks a strategy, set it using the mutation in Section C
   (with an empty `strategyPeriods` array if they just want a single default).
5. Then proceed to the requested operation (typically Section D — trigger calculation).

This gate ensures no calculation runs without an explicit strategy choice.

---

## Step 3 — Run cost basis calculation

After confirming strategy, check the current calculation status (Section A) and
offer to run or re-run the calculation:

1. Fetch status using the query in Section A.
2. If `status` is `IN_PROGRESS`, inform the user it's already running and offer
   to wait:
   > "Cost basis calculation is currently in progress (started at [time]). Would you like me to wait for it to finish?"
3. If `status` is `DONE`, show when it last ran and ask:
   > "Cost basis was last calculated on [lastFinishedAt]. Would you like to
   > recalculate now, or view the existing results?"
4. If `status` is `ITEM_NOT_FOUND`, this org has never calculated — proceed
   directly to trigger.
5. When the user confirms (or on first-time run), trigger the calculation
   using the mutation in Section D.
6. **Poll status** every ~10 seconds until `status = "DONE"`.
7. Once done, automatically proceed to show results per asset (Section E)
   and financial issues (Section F).

This step ensures the user always has fresh results and understands the
calculation state before viewing data.

---

## Available operations

Based on the user's request, follow the appropriate section below.
Many users will come in with a general question like "help me with cost basis" —
in that case, run Steps 1–3 (authenticate, check strategy, run calculation),
then show results.

---

## A. Check cost basis calculation status

Use this when the user asks whether cost basis is running, done, or when it last ran.

```graphql
query CostBasisGetStatus {
  costBasisGetStatus {
    status
    firstStartedAt
    lastFinishedAt
    updatedAt
  }
}
```

`status` values: `DONE`, `IN_PROGRESS`, `ITEM_NOT_FOUND` (never calculated).

Report the status clearly. If `IN_PROGRESS`, let the user know it's still running
and they should wait. If `DONE`, report when it last finished.

---

## B. View current cost basis strategy

Fetches the default strategy and any date-specific strategy overrides.

```graphql
query GetCostBasisStrategyByDate {
  getCostBasisStrategyByDate {
    response {
      strategyPeriods {
        startDate
        endDate
        strategy
      }
      defaultStrategy
    }
  }
}
```

Present the default strategy and any period overrides clearly. Strategies:
`FIFO`, `LIFO`, `AVG`, `MAX_GAINS`, `MAX_LOSSES`, `FIFO_IMPAIRMENT`.

Explain what each means if the user asks:
- **FIFO** — First-in, first-out. Earliest acquired lots are sold first.
- **LIFO** — Last-in, first-out. Most recently acquired lots are sold first.
- **AVG** — Weighted average cost across all lots.
- **MAX_GAINS** — Sells lowest-cost lots first, maximizing realized gains.
- **MAX_LOSSES** — Sells highest-cost lots first, maximizing realized losses (tax-loss harvesting).
- **FIFO_IMPAIRMENT** — FIFO with impairment accounting support.

---

## C. Update cost basis strategy

Use when the user wants to change the default strategy or set strategy periods.

**Always confirm with the user before executing** — changing strategy affects all
future cost basis calculations and requires a recalculation.

```graphql
mutation UpdateCostBasisStrategyByDate(
  $defaultStrategy: CostBasisStrategy!,
  $strategyPeriods: [CBStrategyPeriodInput]!
) {
  updateCostBasisStrategyByDate(
    defaultStrategy: $defaultStrategy,
    strategyPeriods: $strategyPeriods
  ) {
    success
    message
  }
}
```

Variables example:
```json
{
  "defaultStrategy": "FIFO",
  "strategyPeriods": [
    {
      "startDate": "2024-01-01T00:00:00Z",
      "endDate": "2024-12-31T23:59:59Z",
      "strategy": "LIFO"
    }
  ]
}
```

`CostBasisStrategy` enum v