Sprint 1: project skeleton, type system, and all architecture specs
- src/types.hpp: complete UCWM type system in C++20 — 19 enums, 11 facet data types, all core structs (CanonicalObject, Constraint, Facet, GateSignal, WorldState, etc.) with full JSON round-trip serialization - src/main.cpp: smoke test — constructs apple-problem WorldState by hand, serializes to JSON - tests/test_types.cpp: 19 tests, 123 assertions, all passing - CMakeLists.txt: CMake + CPM build with nlohmann/json, spdlog, Catch2 - schemas/: JSON Schema contracts for all UCWM data types - gates/, specialists/, resolver/, synthesis/: language-agnostic interface contracts and domain specs for all pipeline layers - docs/: architecture, vocabulary, decision matrices, roadmap (6 phases, 28 sprints), sprint_001, implementation_constraints Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
165
docs/decision_matrices.md
Normal file
165
docs/decision_matrices.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user