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). A "Depreciation - X" name is read from the chart: under an expense parent, when asset X already has its accumulated depreciation account, or when it carries the Depreciation detail type, it is a depreciation expense and stays an expense; under the fixed asset itself it is accumulated depreciation. When the chart does not show which, either coding passes. Names that do not match any semantic pattern are not penalized.

Ensure every active account has an account number assigned, inside its standard numbering range. Coverage is scored as (accounts_with_numbers / total_active_accounts) × 12. Missing even one number costs points.

Every numbered account must fall in the standard numbering 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 orderly numbering. Each Expense group (a top-level account and its sub-accounts) owns a block of numbers from its first number up to the next group: keep its sub-accounts inside that block in steps of 10, and leave at least 3 free numbers in every group. A group may start on any multiple of 10; a round start such as 6100 is a preference, not a requirement. For all other types, use 10-point steps from the range start (e.g., A/P: 2000, 2010, 2020). The deterministic numberer handles this — do not manually assign numbers.

Keep each accumulated depreciation account under the fixed asset it belongs to (parentId pointing to the asset). The product names it "Accumulated Depreciation - <Asset>" and leaves the asset holding the cost under its own name; that pair passes. A chart that uses "X - Original Cost" bases must give each one a matching "X - Accumulated Depreciation" or "Accumulated Depreciation - X" child. Orphaned depreciation accounts or bases without their depreciation counterpart fail this check.

Each accumulated depreciation account should be numbered at its parent fixed asset + 5. For example, if "Equipment" is 1510, "Accumulated Depreciation - Equipment" should be 1515. An account named "<Asset> - Accumulated Depreciation" is numbered the same way. Do not rename either account.

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).

Name each accumulated depreciation account after its asset. The product's form is "Accumulated Depreciation - <Asset Name>"; "<Asset Name> - Accumulated Depreciation" is also accepted. Do not rename an account from one accepted form to the other. The asset linker (lib/fixed-asset-linker.ts) and the numberer (lib/deterministic-gaap-numbering.ts) read both forms.

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" + "Costs in Excess of Billings" + "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 standard numbering 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.