atelier/matrix/principles-matrix.md

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.