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.