# UCWM Decision Matrices Use this format for every major architecture fork. A decision that is too complex to settle in a sentence deserves a matrix. --- ## Matrix format **Rows** = options under consideration **Columns** = evaluation factors **Each row also includes** a structured summary block ### Standard columns | Column | What it measures | |---|---| | `compute_efficiency` | Ops and memory per inference pass | | `memory_efficiency` | State size and cache pressure | | `latency_cost` | Wall-clock time sensitivity | | `implementation_complexity` | Engineering effort to build correctly | | `training_complexity` | Data, infra, and iteration cost | | `scaling_behavior` | How quality changes with more data/compute | | `mechanistic_interpretability` | Can you understand what the model is doing internally? | | `state_inspectability` | Can intermediate state be read and debugged? | | `constraint_explicitness` | Are constraints visible as typed objects? | | `failure_localizability` | Can a failure be traced to a specific module? | | `update_localizability` | Can a fix be applied without retraining everything? | | `swappability` | Can this component be replaced without cascading changes? | | `extensibility` | How hard is it to add new capability? | | `backward_compatibility` | Does a change break existing contracts? | | `migration_cost` | Cost to shift if this option turns out wrong | | `reasoning_power` | Quality of structured reasoning output | | `generalization_potential` | Expected performance outside training distribution | | `precision` | False positive rate on structured outputs | | `robustness` | Graceful degradation under noisy/adversarial input | | `cognitive_load` | Mental overhead for a solo builder to hold this in mind | | `solo_builder_feasibility` | Can one person build and maintain this? | | `prototype_speed` | Time from decision to working test | | `dependency_risk` | Risk from external libraries, APIs, models | Rating scale: `low` / `med` / `high` or numeric where useful. Unknown cells should say `?` not be left blank. ### Per-row summary block ``` key_benefit: One sentence on the strongest argument for this option key_risk: One sentence on the most likely failure mode unknowns: What you don't know yet that would change this rating what_it_unlocks: What becomes possible if this works what_it_blocks: What becomes harder or impossible if you choose this reversibility: easy / partial / hard — cost of switching away later recommended_now: yes / no / conditional ``` **Note:** Unknown is not the same as bad. Prototype choice is not always final architecture choice. --- ## Matrix 001 — Object Proposal Strategy **Decision:** How should the system produce initial CanonicalObject proposals from raw input? | Option | compute_efficiency | memory_efficiency | implementation_complexity | training_complexity | state_inspectability | failure_localizability | prototype_speed | solo_builder_feasibility | |---|---|---|---|---|---|---|---|---| | A. Rule-based NER + heuristics | high | high | low | none | high | high | high | high | | B. Small fine-tuned span extractor (~100M) | med | med | med | med | med | high | med | med | | C. Prompted general LLM | low | low | low | none | low | low | high | high | | D. Full encoder-decoder proposal model | low | low | high | high | med | med | low | low | ``` Option A — Rule-based NER + heuristics key_benefit: Zero training cost, fully inspectable, fast to iterate contracts against key_risk: Low recall on implicit or unusual entities; won't generalize to new domains unknowns: How many object kinds can be reliably detected with rules alone? what_it_unlocks: Fast contract stabilization; deterministic test fixtures what_it_blocks: Realistic handling of ambiguous or implicit entities reversibility: easy — rules are swappable recommended_now: yes — for first vertical slice Option B — Small fine-tuned span extractor key_benefit: Better recall than rules, bounded output, can be contract-tested key_risk: Requires labeled data; adds training loop before contracts are stable unknowns: Minimum labeled data needed for acceptable recall on target domains? what_it_unlocks: Realistic prototype; near-production object proposal what_it_blocks: Nothing significant reversibility: partial — retraining needed to change object kinds recommended_now: conditional — after contracts stabilize Option C — Prompted general LLM key_benefit: Zero training, fast to prototype key_risk: Output is not contract-typed; failure modes are opaque and inconsistent unknowns: ? what_it_unlocks: Fast exploration what_it_blocks: All downstream contract-testing; structured state guarantees reversibility: easy recommended_now: no — undermines UCWM's core value proposition Option D — Full encoder-decoder proposal model key_benefit: Highest potential recall and precision key_risk: Massive training complexity before any contract is validated unknowns: ? what_it_unlocks: Full generality what_it_blocks: Fast iteration; solo buildability reversibility: hard recommended_now: no ``` --- ## Matrix 002 — Constraint Representation Format **Decision:** What format should constraints use internally? | Option | state_inspectability | constraint_explicitness | swappability | implementation_complexity | reasoning_power | prototype_speed | |---|---|---|---|---|---|---| | A. Typed record structs (per schema) | high | high | high | med | med | med | | B. Predicate logic strings | high | med | med | low | high | med | | C. Graph edges in a knowledge graph | med | med | low | high | high | low | | D. Embedding vectors | low | low | low | low | low | high | ``` Option A — Typed record structs key_benefit: Directly contract-testable; every field is named and typed key_risk: Requires upfront schema design for each constraint type unknowns: How many constraint types are needed before the schema stabilizes? what_it_unlocks: Unit testing of individual constraints; specialist contract validation what_it_blocks: Nothing significant for structured reasoning reversibility: partial — schema changes require migration recommended_now: yes Option B — Predicate logic strings key_benefit: Human-readable; can feed formal solvers key_risk: String parsing adds fragility; harder to type-check unknowns: How to handle probabilistic and defeasible constraints in logic strings? what_it_unlocks: Integration with SMT solvers, Prolog-style inference what_it_blocks: Clean contract testing without a parser layer reversibility: partial recommended_now: conditional — after typed structs prove insufficient Option C — Knowledge graph edges key_benefit: Natural representation for relation-heavy domains key_risk: Graph traversal adds latency; harder to express soft constraints unknowns: Which graph library and query interface? what_it_unlocks: Graph-native reasoning; visualization what_it_blocks: Simple sequential constraint resolution reversibility: hard recommended_now: no Option D — Embedding vectors key_benefit: Fast similarity; compatible with neural downstream key_risk: Zero inspectability; no contract-testing possible unknowns: ? what_it_unlocks: Neural constraint matching what_it_blocks: Everything UCWM stands for reversibility: easy recommended_now: no ``` --- ## How to add a new matrix Copy the template above. Give it the next sequential ID and a clear decision statement. Fill in relevant columns only — not every column applies to every decision. Mark unknowns as `?` rather than guessing. Add the per-row summary block for every option. Archive old matrices as decisions are made, but do not delete them. Past reasoning is provenance.