ADR-004: Content decisions for the initial import

Status: Accepted — ratified by product owner on 2026-11-21. Supersede only with a new ADR.

Date: 2026-11-21

Context

The Phase 0 content audit (CONTENT-INVENTORY.md) left three questions that block a correct

import:

1. The export contains a subject value, "Theory of Accounts", which is **not one of the six

LECPA subjects** defined by PRBOA Resolution No. 30 s. 2022 (FAR, AFAR, Management Services,

Auditing, Taxation, RFBT).

2. 45 of the 57 caseGroupId values referenced by questions have no entry in the export's

caseGroups map — the item-set stimulus text is missing.

3. 1,858 of 2,343 questions (79%) have an empty explanation.

The product owner decided all three on 2026-11-21. This ADR is the record; the seed binary

implements it.

Decision 1 — "Theory of Accounts" maps to Financial Accounting and Reporting

  • Questions whose subject is "Theory of Accounts" are assigned
  • subject = "Financial Accounting and Reporting" at import time.

  • Why FAR: it is the LECPA subject that carries the conceptual-framework and
  • theory-of-accounts coverage. Leaving a subject that no LECPA exam has would create a filter

    category with no exam behind it.

  • The mapping is a single explicit table in the seed binary, not string matching spread across
  • code:

    subject_map = { "Theory of Accounts": "Financial Accounting and Reporting" }.

  • The original value is preserved inside the question body JSON, so the mapping is reversible
  • and no data is destroyed.

  • After this mapping the pool has four LECPA-aligned subject values: Financial Accounting and
  • Reporting, Management Services, Taxation — all three real — plus the mapped rows merged into the

    first. AFAR, Auditing and RFBT remain empty.

    Decision 2 — every referenced case group stays grouped; missing scenarios are marked, not dropped

  • All 57 referenced caseGroupId values get a row in case_groups, including the 45 with no
  • entry in the export.

  • For those 45: title is derived from the representative question's topic, scenario is the
  • empty string, and needs_authoring = true.

  • Why: item sets are served or withheld as a unit (ADR-003). Rejecting the 45 at import would
  • silently drop the 228 questions that carry a caseGroupId, and discarding the grouping would

    destroy the product feature the exam-prep market pays for.

  • Honest consequence: those 45 item sets cannot be *shown* to a learner until scenario text is
  • authored, because a case group without its stimulus is not a usable item set. The

    needs_authoring flag is what the admin UI filters on and what the authoring backlog counts.

  • Numbers: 12 groups defined, 57 referenced, 45 dangling, 228 questions grouped.
  • Decision 3 — the explanation gap is imported as-is, not fabricated

  • Questions with an empty explanation are imported with the empty string preserved. No
  • explanation text is generated, inferred or back-filled.

  • Why: an auto-generated explanation on a graded CPA item is worse than none — it teaches a
  • wrong rationale next to an answer that is marked correct. Fabricating content is out of scope for

    an engineering change.

  • The learner results screen must render an explicit empty state ("No explanation provided for this
  • question"), never a blank panel.

  • Content debt is a queryable count, not a manual list:
  • SELECT count(*) FROM questions WHERE explanation = '' AND NOT archived;

  • Numbers: 1,858 of 2,343 questions (79%).
  • Consequences

  • The pool filter exposes real LECPA subjects only; there is no "Theory of Accounts" category.
  • 45 item sets are invisible to learners until authored — a known, counted gap, not a silent one.
  • 79% of attempts will show no explanation; the results screen must be designed for that as the
  • normal case, not the edge case.

  • All three decisions are data, not code: each is reversible by re-running the seed with a
  • changed subject_map or clearing a flag, with no schema migration.

    Open questions

    1. Who authors the 45 missing scenarios, and by when — is this a launch blocker or a post-launch

    backlog item?

    2. Should explanations be a paid-tier feature once authored, or part of the free pool?

    3. If "Theory of Accounts" later proves to belong under Auditing rather than FAR, is a re-map

    acceptable after users have attempt history against those questions?