# Principles Matrix > Maps every domain principle to the core principle(s) it derives > from. Used to verify that no domain rule is orphaned and to resolve > conflicts. **Core principles key:** C1=Correctness · C2=Clarity · C3=Simplicity · C4=Locality · C5=Reversibility · C6=Composability · C7=Observability · C8=Economy --- ## UI / UX | UI/UX Principle | Core | Why | |---------------------------|------|---------------------------------------| | P1 User Primacy | C2 | Clarity serves the user | | P2 Accessibility | C1 | Correctness for all abilities | | P3 Clarity | C2 | Direct derivation | | P4 Feedback | C7 | Observability for humans | | P5 Forgiveness | C5 | Reversibility of user actions | | P6 Performance | C1 | Correctness includes temporal correctness | | P7 Hierarchy | C2 | Clarity of priority | | P8 Consistency | C2 | Clarity through uniformity | | P9 Simplicity | C3 | Direct derivation | | P10 Reversibility | C5 | Direct derivation | ## API Design | API Principle | Core | Why | |---------------------------|------|---------------------------------------| | P1 Contract Fidelity | C1 | Correctness of the public contract | | P2 Clarity | C2 | Direct derivation | | P3 Predictability | C3 | Simplicity of mental model | | P4 Composability | C6 | Direct derivation | | P5 Versioning | C5 | Reversibility for consumers | | P6 Idempotency | C1 | Correctness under retry | | P7 Performance | C1 | Correctness includes latency | | P8 Security | C1 | Correctness includes safety | | P9 Error Transparency | C7 | Observability of failures | | P10 Stability | C5 | Reversibility of changes | ## Security | Security Principle | Core | Why | |---------------------------|------|---------------------------------------| | P1 Zero Trust | C1 | Correctness requires no false trust | | P2 Least Privilege | C3, C8 | Simplicity of access; economy of trust | | P3 Defense in Depth | C1 | Correctness under partial failure | | P4 Input Validation | C1 | Correctness of inputs | | P5 Output Safety | C1 | Correctness of outputs | | P6 Crypto Correctness | C1 | Crypto failures = correctness failures | | P7 Auditability | C7 | Observability of security events | | P8 Fail Securely | C1 | Correctness of failure modes | | P9 Secret Hygiene | C6, C7 | Composability of secrets; observability | | P10 Surface Minimization | C3, C8 | Simplicity; economy of code | ## Data | Data Principle | Core | Why | |---------------------------|------|---------------------------------------| | P1 Truth | C1 | Schema must match domain | | P2 Normalization | C1, C3 | Correctness without duplication; simplicity | | P3 Invariants in Schema | C1 | Correctness enforced | | P4 Migration Safety | C5 | Reversibility of changes | | P5 Indexing with Intent | C7 | Observability of query patterns | | P6 Naming Consistency | C2 | Direct derivation | | P7 Type Fidelity | C1, C2 | Correctness; clarity | | P8 Lifecycle Awareness | C1 | Correctness includes lifecycle | | P9 Referential Integrity | C1 | Correctness of relationships | | P10 Performance Awareness | C1 | Correctness includes cost | ## Testing | Testing Principle | Core | Why | |---------------------------|------|---------------------------------------| | P1 Tests as Specification | C2 | Tests document intent | | P2 Independence | C4 | Locality of test execution | | P3 Determinism | C1 | Correctness is reproducible | | P4 Fast Feedback | C3, C8 | Simplicity; economy of time | | P5 Coverage of Behavior | C1 | Correctness of behavior | | P6 Failure Specificity | C7 | Observability of failures | | P7 Realism | C1 | Correctness in real conditions | | P8 Maintainability | C3, C8 | Simplicity; economy of maintenance | | P9 Edge Case Coverage | C1 | Correctness at boundaries | | P10 No Test Theater | C1, C8 | Correctness; economy of test code | ## Performance | Perf Principle | Core | Why | |---------------------------|------|---------------------------------------| | P1 Measure First | C7 | Observability precedes optimization | | P2 Critical Path Focus | C3 | Simplicity of scope | | P3 Complexity Awareness | C1 | Correctness includes cost | | P4 Resource Bounds | C1, C8 | Correctness; economy of resources | | P5 Caching with Intent | C3, C6 | Simplicity; composability | | P6 Lazy by Default | C8 | Economy of computation | | P7 Async When Independent | C3 | Simplicity of flow | | P8 Budget Discipline | C8 | Economy of resources | | P9 Perceived Performance | C1 | Correctness from user's view | | P10 Regression Prevention | C7 | Observability of regressions | ## Observability | Obs Principle | Core | Why | |---------------------------|------|---------------------------------------| | P1 Structured by Default | C2, C7 | Clarity; observability | | P2 Correlation | C7 | Direct derivation | | P3 Sufficient Context | C7, C2 | Observability; clarity | | P4 Cardinality Discipline | C8 | Economy of storage/cost | | P5 Sampling with Intent | C8 | Economy of observability budget | | P6 No Secrets in Obs | C1, C6 | Correctness; composability | | P7 Actionable Alerts | C7, C8 | Observability; economy of attention | | P8 SLI/SLO Awareness | C1 | Correctness defined | | P9 Cost Awareness | C8 | Direct derivation | | P10 Debuggability | C2, C7 | Clarity; observability | ## Errors | Error Principle | Core | Why | |---------------------------|------|---------------------------------------| | P1 Errors are Data | C2, C7 | Clarity; observability | | P2 Fail Loudly | C7 | Direct derivation | | P3 Fail Specifically | C2, C7 | Clarity; observability | | P4 Preserve Context | C7 | Direct derivation | | P5 Recoverable When Possible | C1, C5 | Correctness; reversibility | | P6 Unrecoverable Means Stop | C1 | Correctness of failure mode | | P7 Errors are Boundaries | C6 | Composability | | P8 User-Facing Errors are UX | C2 | Clarity for users | | P9 Errors are Logged | C7 | Direct derivation | | P10 Errors Don't Lie | C1, C2 | Correctness; clarity | ## Documentation | Doc Principle | Core | Why | |---------------------------|------|---------------------------------------| | P1 Documentation is Code | C3, C8 | Simplicity; economy of process | | P2 Audience Awareness | C2 | Direct derivation | | P3 Examples are Mandatory | C2 | Direct derivation | | P4 Currency | C1 | Correctness of docs | | P5 Discoverability | C2 | Direct derivation | | P6 Conciseness | C3, C2 | Simplicity; clarity | | P7 Structure | C2 | Direct derivation | | P8 Why Over What | C2 | Direct derivation | | P9 Living Documents | C1, C5 | Correctness; reversibility | | P10 Public by Default | C6 | Composability | ## Concurrency | Concurrency Principle | Core | Why | |---------------------------|------|---------------------------------------| | P1 Immutability by Default | C1, C3 | Correctness; simplicity | | P2 Single Responsibility | C3, C6 | Simplicity; composability | | P3 Boundaries are Locks | C4, C6 | Locality; composability | | P4 Determinism Over Speed | C1 | Correctness precedes performance | | P5 Lock Minimization | C3 | Simplicity | | P6 No Silent Races | C7 | Observability of races | | P7 Cancellation Support | C5 | Reversibility of work | | P8 Timeout Discipline | C1 | Correctness of blocking | | P9 Bounded Queues | C1, C8 | Correctness; economy of memory | | P10 Test for Races | C1 | Correctness verification | ## DevOps | DevOps Principle | Core | Why | |---------------------------|------|---------------------------------------| | P1 Reproducibility | C1 | Correctness of environments | | P2 Automation | C3, C8 | Simplicity; economy of effort | | P3 Observability | C7 | Direct derivation | | P4 Rollback First | C5 | Direct derivation | | P5 Progressive Delivery | C5, C1 | Reversibility; correctness gradually | | P6 Configuration as Code | C1, C3 | Correctness; simplicity | | P7 Immutability | C1 | Correctness of deploys | | P8 Security at Every Layer | C1 | Correctness includes security | | P9 Documentation in Pipeline | C2 | Clarity of operations | | P10 Failure as Expected | C1, C7 | Correctness; observability | ## Infrastructure as Code | IaC Principle | Core | Why | |---------------------------|------|---------------------------------------| | P1 Declarative Intent | C2, C3 | Clarity; simplicity of declaration | | P2 Idempotence | C1 | Correctness of repeated apply | | P3 State is Truth | C1, C7 | Correctness; observability of reality | | P4 Plan Before Apply | C5 | Reversibility of changes | | P5 Version Everything | C5 | Reversibility of reproduction | | P6 Modules Compose | C6 | Composability of infrastructure | | P7 Least Privilege Providers | C1 | Correctness via security | | P8 Remote State with Locking | C1, C4 | Correctness; locality of state | | P9 Drift is Recoverable | C5, C7 | Reversibility; observability of drift | | P10 Secrets Never in Code | C1 | Correctness includes secret safety | ## Kubernetes | K8s Principle | Core | Why | |---------------------------|------|---------------------------------------| | P1 Declarative Desired State | C1, C2 | Correctness; clarity of intent | | P2 Pods are Mortal | C5 | Reversibility of workloads | | P3 Labels Select | C2, C6 | Clarity; composability of selection | | P4 Requests and Limits | C1, C8 | Correctness; economy of resources | | P5 Probes Drive Health | C1, C7 | Correctness; observability of health | | P6 Namespaces Bound Blast | C4 | Locality of blast radius | | P7 RBAC by Intent | C1 | Correctness via security | | P8 Storage is Explicit | C4, C5 | Locality; reversibility of data | | P9 Config and Secrets Sep | C2 | Clarity of configuration | | P10 Roll Forward, Roll Back | C5 | Reversibility of deploys | ## GitOps + Operators | GitOps Principle | Core | Why | |---------------------------|------|---------------------------------------| | P1 Git is the Source of Truth | C1, C5 | Correctness of source; reversibility via history | | P2 Declarative Over Imperative | C2, C3 | Clarity of intent; simplicity of expression | | P3 Pull, Don't Push | C1, C4 | Correctness via security; locality of credentials | | P4 Continuous Reconciliation | C7, C1 | Observability of drift; correctness of converge loop | | P5 State is Immutable and Versioned | C5 | Reversibility through history | | P6 Operators Encode Domain Knowledge | C6, C2 | Composability of expertise; clarity of operations | | P7 Progressive Delivery is Reversible | C5, C1 | Reversibility of promotion; correctness of abort | | P8 Reconcile, Don't Mutate by Hand | C1, C7 | Correctness of source of truth; observability of drift | | P9 Failure is Observable and Surfaced | C7 | Observability of sync/rollout health | | P10 Least Privilege Reconciliation | C1, C8 | Correctness via security; economy of trust | ## AI / ML | AI/ML Principle | Core | Why | |---------------------------|------|---------------------------------------| | P1 Reproducibility is the First Class | C1, C5 | Correctness of runs; reversibility of reproduction | | P2 Data is Versioned, Not Just Code | C5, C7 | Reversibility of data; observability of dataset lineage | | P3 Lineage is Traceable End-to-End | C7, C1 | Observability of predictions; correctness of provenance | | P4 Evaluation is Defined Before Training | C1, C2 | Correctness of metrics; clarity of thresholds | | P5 Models are Versioned Artifacts | C5, C6 | Reversibility of model rollbacks; composability of registry | | P6 Serving is Observable | C7 | Observability of inference | | P7 Drift is Expected and Detected | C7, C1 | Observability of drift; correctness of detection | | P8 Inference Inputs are Validated | C1 | Correctness at serving boundary | | P9 Pipelines Compose, Notebooks Don't | C6, C2 | Composability of steps; clarity of contracts | | P10 Rollback Includes the Model | C5 | Reversibility at the model layer | ## i18n | i18n Principle | Core | Why | |---------------------------|------|---------------------------------------| | P1 Source Language is a Locale, Not the Default | C2, C1 | Clarity; correctness of localization model | | P2 Locale Identifiers are Standardized | C2, C6 | Clarity; composability of BCP 47 | | P3 Resources are External, Not Inline | C4, C6 | Locality of strings; composability of resources | | P4 Plural and Gender are Parameterized | C1, C6 | Correctness across locales; composability of message format | | P5 Formatting is Locale-Aware | C1, C7 | Correctness of formats; observability of format correctness | | P6 Text Direction is a Layout Primitive | C1, C4 | Correctness of RTL/bidi; locality of direction | | P7 Layout Accommodates Expansion | C8, C3 | Economy of rework; simplicity of flexible layout | | P8 Pseudo-Locales Test Early | C7, C5 | Observability of bugs early; reversibility of finding late | | P9 Images and Icons are Cultural | C1, C2 | Correctness; clarity of cultural meaning | | P10 Translation is Reversible and Versioned | C5 | Reversibility of localization changes | ## Compliance | Compliance Principle | Core | Why | |---------------------------|------|---------------------------------------| | P1 Audit Logs are Append-Only | C1, C5 | Correctness of audit; reversibility of immutable record | | P2 Every Significant Action is Logged | C7, C1 | Observability of actions; correctness of audit set | | P3 Retention is Policy, Not Storage | C5, C8 | Reversibility of lifecycle; economy of storage | | P4 Policy is Code | C6, C2 | Composability of policy; clarity of rules | | P5 Policy is Evaluated as a Gate | C1, C5 | Correctness of enforcement; reversibility of block | | P6 Evidence is Collected Continuously | C7, C3 | Observability of posture; simplicity of audit | | P7 Identity is Attributable | C1, C7 | Correctness of attribution; observability of subject | | P8 Subject Access is Honored | C1, C5 | Correctness of rights; reversibility of deletion/export | | P9 Secrets and Sensitive Data are Redacted in Audit | C1, C3 | Correctness via security; simplicity of structural redaction | | P10 Compliance Posture is Observable | C7, C1 | Observability of compliance; correctness of posture | ## Coverage Summary (post-v0.3) - 17 domains (11 v0.1 + 2 v0.2: infrastructure-as-code, kubernetes; 4 v0.3: gitops-operators, ai-ml, i18n, compliance) - 170 domain principles total (110 v0.1 + 20 v0.2 + 40 v0.3) - Every domain P-rule traces to ≥1 core C-rule (C1–C8). No orphans.