# Guided Manual Review Pilot (Broker Review Queue)

Use this when the user asks to pilot manual mapping on real runtime review items after the broker review queue has been hardened.

## Scope and safety

- This is a **runtime metadata workflow only**: no productive `positions_snapshot`, `transactions`, `cash_balances`, cash snapshots, ledger rows, or reports with real equity/ETF values.
- Prefer a small pilot of **1–3 items** from the least noisy source (e.g. True Wealth before PostFinance). Keep Raiffeisen aggregate-only rows defensive and blocked for instrument imports.
- Report only aggregate counts and status transitions. Do not output quantities, values, account balances, raw rows, or sensitive file contents.
- Use existing runtime review items; do not copy real broker/bank files into the repo.

## Selection criteria

Choose items that are:

1. ETF/equity-like and not cash for the first pilot.
2. Not `aggregate_only` and not total/category rows.
3. Clearly identifiable by ISIN already present in the source label or another safe metadata field.
4. In a source/account context that can be mapped without mixing cash and brokerage/robo accounts.

If no item has a reliable ISIN/ticker/exchange, do not guess. Leave it `needs_manual_review` and ask for a better export with ISIN/Valor/ticker/account columns.

## Safe action sequence

For each selected review item:

1. Record pre-counts: readiness by source, status counts, and productive table counts.
2. Add/update metadata-only platform/account records if the needed review account does not exist. Audit these records and label them explicitly as review metadata only.
3. Add/update metadata-only instrument records only when an identifier is reliable (prefer ISIN). Audit the instrument metadata creation/update.
4. Call the review action functions rather than ad-hoc SQL where possible:
   - `update_review_item_isin(...)`
   - `update_review_item_ticker_exchange(..., confirm_ticker_exchange=True)` when ticker+exchange are known
   - `confirm_review_item_account_mapping(...)`
   - `confirm_review_item_snapshot_date(...)` when the snapshot date is manually confirmed as metadata only
   - `confirm_review_item_instrument_mapping(...)`
5. If parser presence flags are wrong but the source structure clearly has quantity/value cells, correct **presence booleans only** (`detected_quantity_present`, `detected_market_value_present`) with an audit event. Never store or echo the actual numeric values during the pilot.
6. Refresh readiness. Only call `mark_review_item_resolved(...)` after readiness is `ready_for_import`.
7. Verify post-counts and productive table counts remained unchanged.

## Verification checklist

- `ready_for_import` increased only for the intended source/items.
- Selected items have audit history for ISIN, ticker/exchange, account mapping, snapshot confirmation, instrument mapping, and resolve; metadata-only platform/account/instrument changes are audited too.
- Data Quality Center shows updated readiness counts.
- Manual Review Queue shows the expected statuses (`resolved` + `ready_for_import` for completed pilot items).
- Productive tables (`positions_snapshot`, `transactions`, `cash_balances`, and ledger/cash snapshot tables if present) are unchanged.
- Run compile, pytest, Git-safety, and Git status. If no code changed, do not commit.

## Pitfalls

- Do not set `ready_for_import` by direct status edits. Let readiness logic derive it from required metadata and confirmations.
- Do not treat name-only labels as mapped; ISIN is preferred, ticker+exchange requires explicit confirmation.
- Do not import cash or aggregate/control rows in the first ETF/equity pilot.
- Do not mistake boolean presence metadata for value import. Presence flags may be corrected, but actual quantities/values remain outside chat/Git and are not written to productive portfolio tables in this phase.