Run AI auto-suggest mapping

Who does this: FS Preparer · Senior Accountant · Platform Admin When: Trial balance is uploaded and every row needs to be assigned an SFRS taxonomy key. Result: Every FsTrialBalanceItem has a non-null taxonomyKey populated by Claude with a confidence and rationale. The engagement does not automatically advance to TB_MAPPED unless every row mapped on the first pass — typically 90%+ of rows.

Auto-suggest is the bulk path. It does not replace the reviewer; it gives the reviewer a starting point + a confidence band per row, so the human attention budget can focus on the LOW / UNCLASSIFIED rows.

Before you start

• [ ] Engagement at TB_UPLOADED (see Upload a trial balance).
• [ ] An Anthropic API key is configured in the worker environment (or the mock adapter is enabled for dev — check pnpm dev worker logs).
• [ ] You hold CONFIRM_FS_MAPPING (held by FS_PREPARER, FS_REVIEWER, SENIOR_ACCOUNTANT, PLATFORM_ADMIN).

Steps

1. Open the engagement; switch to the Mapping tab.
2. The table shows every TB row with an empty taxonomyKey column.
3. Click Auto Suggest in the top right.
4. The handler enqueues auto-suggest-mapping. The UI shows a polling indicator.
5. After ~10–30 seconds the table refreshes with confidence badges per row:
   • HIGH — accept by default
   • MEDIUM — read the rationale tooltip; accept or pick from alternatives
   • LOW — always confirm explicitly or override
   • UNCLASSIFIED — no suggestion; manual mapping required
6. (Optional) Click Re-run if you want a fresh suggestion pass. Auto-suggest does not clobber manual overrides (isOverride = true rows are preserved).

How to know it worked

1. The Mapping table shows a taxonomyKey and a taxonomyLabel on most rows.
2. Each row carries a confidence chip and a rationale tooltip (hover over the chip).
3. The activity log shows fs.mapping.auto_suggested with inputTokens and outputTokens in the payload.

Common situations

If you see…	It means…	What to do
> 30% of rows return UNCLASSIFIED	The TB columns confused the parser, or the descriptions are too generic	Inspect the TB; verify sign normalisation; ensure account descriptions are populated; rerun. See Many unclassified
All rows return LOW	Claude was given a TB that doesn't look like a TB (e.g. a journal export)	Verify the source file is a true TB. Re-upload if needed.
Auto-suggest call fails (timeout / error)	Claude API issue or worker not connected	Check worker logs; retry; map manually if persistent
Auto-suggest returned the same row mapped to two different keys	Should not happen — would indicate a bug	File an issue with the activity-log payload from fs.mapping.auto_suggested

Related runbooks

• Override a low-confidence mapping — for LOW / UNCLASSIFIED rows
• FS-03 userflow — API trace and verification
• Financial Statements SOP §6 / Step 3.0
• Many UNCLASSIFIED rows