Skip to content
Fera Docs

Search is only available in production builds. Try building and previewing the site to test it out locally.

TECHSPEC's "TBD — see OQ.md" pointers all point at questions that are already RESOLVED

Источник: dev/fera-research/docs/oc1/003-techspec-tbd-pointers-resolved.md (read-only; сгенерировано scripts/sync-docs.mjs)

TECHSPEC’s “TBD — see OQ.md” pointers all point at questions that are already RESOLVED

Section titled “TECHSPEC’s “TBD — see OQ.md” pointers all point at questions that are already RESOLVED”

  • kind: problem

  • area: modules / storage / ui / perf

  • evidence — every one of these TBDs in TECHSPEC.md cites an OQ that carries a Resolved marker in OQ.md:

    TECHSPEC site says OQ entry OQ.md status
    TECHSPEC.md:149-152 regex two-phase “threshold” decided in ADR-012 OQ-011 OQ.md:288 “Resolved (2026-09-30) → decision sketch, calibration pending.”
    TECHSPEC.md:163-164 “which fields count as metadata vs content … see OQ.md” Open OQ-005 OQ.md:117 “Resolved (2026-10-01) → ADR-031. Full field audit recorded…”
    TECHSPEC.md:193-194 Lottie backend “A/B … before deciding default” decided OQ-004 OQ.md:96 “Resolved (2026-09-30) → sequencing decision. tlottie is the …”
    TECHSPEC.md:195-204 sticker cache “Decide raw-vs-compressed … see OQ.md” researched OQ-003 RESEARCH-OQ-003.md (405 lines) is the answer
    TECHSPEC.md:214-216 predictor log “or sanakirja directly if kept separate … TBD, see OQ.md” decided OQ-009 OQ.md:215 “Status: RESOLVED (2026-10-02) → see resolution note at the end.”
    TECHSPEC.md:262-263 hit-testing “decide single-pass vs two-pass before significant implementation investment” decided OQ-002 OQ.md:48 “Resolved (2026-09-30) → ADR-030. Single-pass.”
    TECHSPEC.md:359 “Plugin container format: open — deferred to the author (OQ-013)” decided OQ-013 OQ.md:330 title: “Plugin container format — Lattice (.lttc)”; OQ.md:702 “Resolved details (2026-10-01, author’s answers)”
    TECHSPEC.md:446-447 benchmark scene “parameters TBD — see OQ.md” decided OQ-006 OQ.md:130 “Status: RESOLVED (2026-10-02, author approved the draft as-is)”
    TECHSPEC.md:465 “…HoF rendering layer maturation, pixel-1:1 passes” decided OQ-002/014 OQ.md:476 “Resolved (2026-09-30) → hybrid: Vello + Parley renderer”

    Corpus rule being violated — /home/nikki/dev/fera-project-design/README.md:41-45: “New decisions get recorded here (ADR for architecture, OQ for deferred questions)… An OQ resolved becomes an ADR (or an ADR addendum) and the OQ entry is marked Resolved → see ADR-XXX.” The marker discipline is applied religiously inside OQ.md (12 Resolved markers) and applied nowhere in TECHSPEC.md/RFC.md, which is why the drift exists.

  • severity: mid

Суть / Substance

Section titled “Суть / Substance”

TECHSPEC is described by README.md:20 as the “concrete buildable breakdown” — the doc an implementer actually codes from. Nine of its open decisions are pointers into OQ.md, and every single one of those OQs is resolved. TECHSPEC therefore tells the implementer that nine things are undecided when all nine have answers, three of them in ADRs it already cites elsewhere in the same document.

This is not just wasted reading. Three of the pointers actively mislead about the order of work:

  1. TECHSPEC.md:262-263 says the single-pass vs two-pass hit-testing decision must happen “before significant implementation investment”. It is already decided (ADR.md:1013, single-pass, à la egui). A reader who trusts TECHSPEC will schedule a design pass that is closed, or worse, implement two-pass because “the decision is still open”.
  2. TECHSPEC.md:359 calls the plugin container format “open”, while OQ.md:330 names it (Lattice, .lttc) and ADR.md:422-423 (“Companion to OQ-013’s scope decision that Lattice … is for WASM plugins only”) has already consumed that answer as an input. ADR-024’s whole distribution design rests on it.
  3. TECHSPEC.md:446-447 gives a benchmark scene as “TBD … strawman”, while OQ.md:130 records it as approved 2026-10-02 and RESEARCH-OQ-003.md:380-384 already uses exact parameters (50 concurrent stickers, 60 and 75 fps ticks) as [prov] gates. The strawman “chat with 5000 messages, 50 concurrently-animating stickers” is close to the real scene but is not the scene the gates use.

Варианты решения (tradeoffs)

Section titled “Варианты решения (tradeoffs)”
  • (A) Inline the resolutions into TECHSPEC (replace each TBD with the decided answer + ADR pointer). Best for implementers, biggest diff.
  • (B) Keep pointers, add → Resolved, see ADR-XXX markers mirroring OQ.md. Cheap, keeps TECHSPEC short.
  • (C) Declare TECHSPEC a phase-0 snapshot and add a “superseded pointers” appendix. Cheapest, but leaves the doc that people code from wrong.

Предлагаемое решение

Section titled “Предлагаемое решение”

(B) now, (A) opportunistically. The markers are a one-line-per-site edit that stops the bleeding without a rewrite; then fold each resolution into the body as the corresponding workstream is picked up.

Concretely, per site:

  • :149-152 → state the resolved two-phase decision (ADR-012) and keep only the calibration constant as genuinely open (OQ-011’s own marker says “calibration pending” — that part is real).
  • :163-164 → delete the TBD, point at the ADR-031 field audit.
  • :193-194 → tlottie is the default per OQ-004; velato stays a non-blocking experiment.
  • :195-204 → the raw-vs-compressed question is answered by RESEARCH-OQ-003 (read it before re-deciding).
  • :214-216 → apply the OQ-009 resolution note at the end of OQ-009.
  • :262-263 → single-pass, per ADR-030. This one is on the critical path for the HoF layer.
  • :359 → Lattice .lttc for WASM plugins; plain signed dylibs for native (ADR-024).
  • :446-447 → replace the strawman with the approved OQ-006 scene.

Also worth one line in README.md: extend the Resolved-marker convention from OQ.md to TECHSPEC.md/RFC.md so the next drift is visible.