ucwm/docs/decision_matrices.md

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.