How the optimizer makes decisions you can audit.

Every account must have an accountType that is one of the 15 official QBO types: Bank, Accounts Receivable, Other Current Assets, Fixed Assets, Other Assets, Accounts Payable, Credit Card, Other Current Liabilities, Long Term Liabilities, Equity, Income, Other Income, Cost of Goods Sold, Expenses, Other Expense. No empty values, no custom types.

Never mis-bucket statement placement. Bank, AR, Fixed Assets, Other Assets, Other Current Assets, AP, Credit Card, Liabilities, and Equity belong on the Balance Sheet. Income, Other Income, COGS, Expenses, and Other Expense belong on the Income Statement. A type that cannot be resolved to a canonical QBO type fails this criterion.

When you assign a detailType, it MUST be one of QBO's allowed detail types for that accountType. For example, a Bank account's detailType must be one of Checking, Savings, MoneyMarket, etc. See types/qbo-account-types.ts QBO_DETAIL_TYPES for the complete taxonomy. Missing detailType is not penalized by this criterion — only mismatches.

Common account names dictate their type. The reference table below lists every name pattern the scorer checks — pulled directly from lib/account-name-patterns.ts so it is always in sync. Patterns are advisory: only matched-but-mistyped accounts cost points; novel names that match no row are not penalised.

When an account name clearly indicates a contra-account, a prepaid, or returns/allowances, its accountType AND detailType must match the canonical pairing. Examples: "Prepaid Insurance" → Other Current Assets / Prepaid Expenses (NOT Expense). "Allowance for Doubtful Accounts" → Other Current Assets / Allowance for Bad Debts. "Accumulated Depreciation - X" → Fixed Assets / Accumulated Depreciation. "Sales Returns & Allowances" → Income / Discounts/Refunds Given (NOT Other Income, NOT Expense). Names that do not match any semantic pattern are not penalized.

Ensure every active account has a GAAP-compliant account number assigned. Coverage is scored as (accounts_with_numbers / total_active_accounts) × 12. Missing even one number costs points.

Every numbered account must fall in the GAAP range for its type. The exact ranges are listed in the reference table below and come directly from services/gaap-ranges.ts — they are authoritative. An account tagged with the WRONG TYPE will fail this check even if the number is "reasonable", so classify types correctly first, then assign numbers inside the type's range.

Every account number must be unique across the entire chart. Duplicates cost 1 point each. The deterministic numberer prevents this — never override its output.

Use consistent numbering patterns. For Expense accounts: parent categories at 100-point boundaries (6000, 6100, 6200), children at 10-point increments (6010, 6020, 6030). For all other types, use 10-point increments from the range start (e.g., A/P: 2000, 2010, 2020). Avoid gaps larger than 100 within the same parent group. The deterministic numberer handles this — do not manually assign numbers.

For every Fixed Asset base "X - Original Cost" there must be a matching "X - Accumulated Depreciation" child (parentId pointing to the base). Orphaned depreciation accounts or bases without their depreciation counterpart fail this check. Use the canonical suffix form — never the prefix form ("Accumulated Depreciation - X").

Each "X - Accumulated Depreciation" account should be numbered at its parent + 5. For example, if "Equipment - Original Cost" is 1510, "Equipment - Accumulated Depreciation" should be 1515.

Every "- Accumulated Depreciation" account must have a balance ≤ 0. A positive balance indicates either a sign error in posted entries or an account misclassified as Accum. Depr. when it is actually a regular asset. Skip this check for accounts with no balance recorded (treat as not-yet-posted).

Always name depreciation accounts as "<Asset Name> - Accumulated Depreciation" (suffix form). Never use "Accumulated Depreciation - <Asset Name>" (prefix form). The deterministic numberer at lib/deterministic-gaap-numbering.ts:216 and the asset linker at lib/fixed-asset-linker.ts both detect depreciation accounts by the suffix — the prefix form will be missed entirely.

QBO supports up to 5 levels of nesting but deep trees hurt readability. Keep all accounts within 3 levels of a root. Accounts deeper than 3 levels should be flattened or re-parented.

QBO enforces that a child account must share its parent's accountType. A Bank parent can only have Bank children; a Fixed Assets parent can only have Fixed Assets children. Mismatches will be rejected by QBO sync.

Every populated parentId must point to an account that exists in the chart. Orphan references (parentId pointing to a missing/deleted account) will cause QBO sync failures and display bugs.

When a parent grows beyond ~12 direct children, split it into 2–3 logical sub-groups. Example: instead of "Operating Expenses" with 25 children, create "Operating Expenses → Office (10), Travel (8), Professional Services (7)". The 12-child threshold matches typical scan-list cognitive load.

Never produce a chart where a child account has a lower number than its parent (e.g., parent 6100 with child 6050). The deterministic numberer at lib/deterministic-gaap-numbering.ts guarantees parent < child by DFS traversal. If a violation appears, the chart was numbered outside the canonical pipeline and must be re-numbered through assignGaapNumbers().

A good chart groups related accounts under type headers or parent accounts. Aim for at least 20% of non-header accounts to reference a parentId, or create header-type parents (isParent=true) for each top-level account type (Bank, A/R, Fixed Assets, Expenses, etc.). A completely flat chart with no hierarchy is a red flag — even a minimal "Operating Expenses" parent grouping its children adds clarity at zero cost.

If the business has an industry that maps to a curated list (see lib/industry-required-accounts.ts), ensure the chart contains at least one account matching each required pattern. Example: Construction → "Work in Progress" + "Job Costs" + "Subcontractor Expenses" + "Retainage" + "Materials". Missing any listed requirement flags that account type as absent.

A parent account with no children is visual noise — flatten it or remove it. If isParent is set but no account has this parentId, it fails this check.

Account names must describe real categories. Never ship names containing "todo", "tbd", "xxx", "temp", "test", "unnamed", or similar placeholder tokens. These indicate incomplete categorization.

A complete chart has at least some active accounts on both the balance sheet and the income statement. An empty P&L or empty BS indicates the chart is incomplete and cannot produce financial statements.

Each account in the final output must have a unique name. Avoid renaming distinct accounts to identical strings during consolidation steps; if consolidation is intended, merge the accounts into a single row.

Every account must satisfy 4 cross-dimensional invariants: (1) number falls in the GAAP range for accountType; (2) parentId resolves to an existing account; (3) child accountType matches parent accountType; (4) child number > parent number. These invariants are automatically reconciled by services/gaap-ranges.ts crossValidateAndReconcile() in the production pipeline — the AI should not produce charts that fail them in the first place.

Every account must have a descriptive name. Accounts with empty, null, or whitespace-only names are data integrity bugs that will break import and reporting.

Parent-child relationships must form a forest (trees), not a graph with cycles. An account cannot be its own ancestor. Cycles break hierarchy traversal and reporting.

Account numbers must be positive. Zero or negative numbers indicate corrupt data or a typo that will fail QBO validation on import.

Account numbers must be unique. Two accounts sharing the same number will collide in QBO and break reporting.

QBO rejects account names longer than 100 characters at import. Keep names concise and specific.

Account names should avoid characters that QBO rejects or that break CSV/JSON interchange. Disallowed: @, %, *, straight quotes (") and ('), angle brackets (<, >). Ampersand (&) and hash (#) are allowed by QBO and common in real names (e.g., "Payroll & Benefits"), so we do not flag them.

Every production-ready chart of accounts must include accounts covering these critical GAAP functions: (1) Cash or Bank; (2) Accounts Receivable; (3) Accounts Payable; (4) Equity; (5) Retained Earnings. Matching is by canonical account type first, then by common name patterns — so a "Checking Account" typed as Bank covers Cash, and an "Owner Capital" account covers Equity.