# matlus.com

> Shiv Kumar on how software should be built, and on keeping that judgment
> intact when a language model is doing the typing. Programming With Intent
> (PWI) is operationalized guidance with worked examples in Python and C#.

Every article and chapter has a raw markdown companion with no navigation or sidebar.

## Sections

- [PWI](https://matlus.com/pwi/): Programming With Intent chapters and pillars.
- [Acceptance Testing](https://matlus.com/acceptance-testing/): functional testing at the boundary.
- [Writing](https://matlus.com/writing/): essays and video-based articles.
- [Media](https://matlus.com/media/): articles with video or audio companions.
- [About](https://matlus.com/about/): about Shiv Kumar.

## Writing

- [Clean Abstractions Around Libraries](https://matlus.com/writing/clean-abstractions-around-libraries/): A library boundary owns the application's contract even when its terms match the library's. It contains provider types, validation, failures, and configuration, and keeps replacement possible. Markdown: https://matlus.com/writing/clean-abstractions-around-libraries.md
- [Intentional Model Design](https://matlus.com/writing/intentional-model-design/): A model should express required fields, genuine absence, and distinct variants in its type. Python unions and C# records encode those promises, while boundaries check external values. Markdown: https://matlus.com/writing/intentional-model-design.md
- [Jev: A Practical Reference](https://matlus.com/writing/jev-practical-reference/): Jev makes bounded semantic judgments with Choice, Score, and Noul; code handles exact work and policy, while evaluation and confidence gates determine when to act or escalate. Markdown: https://matlus.com/writing/jev-practical-reference.md
- [Skills versus Controlled Workflows](https://matlus.com/writing/skills-versus-controlled-workflows/): When a useful answer is enough, and when you also have to demonstrate that a prescribed procedure was followed. Markdown: https://matlus.com/writing/skills-versus-controlled-workflows.md
- [The AI-Native Lifecycle](https://matlus.com/writing/the-ai-native-lifecycle/): What it takes to engineer both gates rather than widen them, when generation runs at machine speed and trust is the thing in short supply. Markdown: https://matlus.com/writing/the-ai-native-lifecycle.md
- [Stampede at the Gates](https://matlus.com/writing/stampede-at-the-gates/): AI did not break the software lifecycle. It removed the speed limit that was concealing how fragile the lifecycle already was. Markdown: https://matlus.com/writing/stampede-at-the-gates.md
- [Prefer Composition Over Inheritance](https://matlus.com/writing/prefer-composition-over-inheritance/): Composition keeps a configuration provider's capabilities limited to what its project needs. The refactor uses self-contained settings providers, a shallow base, and restrained reuse. Markdown: https://matlus.com/writing/prefer-composition-over-inheritance.md
- [Always Use the "as" Operator? No Thank You!](https://matlus.com/writing/always-use-as-operator-no-thank-you/): Use a cast instead of `as` when the type is expected, so a mismatch raises InvalidCastException. Use `is` when the type genuinely varies and keep only guards backed by a real case. Markdown: https://matlus.com/writing/always-use-as-operator-no-thank-you.md
- [Validating Formal Arguments? No Thank You!](https://matlus.com/writing/validating-formal-arguments-no-thank-you/): Validate and clean data at the front and back doors; skip checks on internal formal arguments. Immutable DTOs preserve trust, one exception reports all errors, and black box tests exercise the doors. Markdown: https://matlus.com/writing/validating-formal-arguments-no-thank-you.md
- [Separate State from Behavior? Yes Please!](https://matlus.com/writing/separate-state-from-behavior/): Separating state from behavior simplifies object-oriented systems: immutable DTOs carry data, while managers compose collaborators and make operations explicit at call sites. Markdown: https://matlus.com/writing/separate-state-from-behavior.md
- [Design Nugget: Evolution To Strategy](https://matlus.com/writing/design-nugget-evolution-to-strategy/): Build a working baseline, then change the design for a concrete benefit; a log parser evolves through a switch, delegates, and Strategy to test that judgment. Markdown: https://matlus.com/writing/design-nugget-evolution-to-strategy.md
- [Mocking? No Thank You!](https://matlus.com/writing/mocking-no-thank-you/): Test whole features through the public surface so regression tests survive later design changes. Class mocks bind tests to internals; transport doubles cover rare external failures. Markdown: https://matlus.com/writing/mocking-no-thank-you.md
- [Dependency Injection? No Thank You!](https://matlus.com/writing/dependency-injection-no-thank-you/): Dependency injection exposes private collaborators to callers when used for every internal relationship. Keep classes self-contained and let business code choose real variation. Markdown: https://matlus.com/writing/dependency-injection-no-thank-you.md
- [Interfaces? No Thank You!](https://matlus.com/writing/interfaces-no-thank-you/): C# interfaces do not inherently create contracts or loose coupling. Composition handles hierarchy conflicts; capability interfaces and structural typing let consumers see only what they need. Markdown: https://matlus.com/writing/interfaces-no-thank-you.md
- [Extension Methods? No Thank You!](https://matlus.com/writing/extension-methods-no-thank-you/): Keep project-specific helpers as static methods: extension methods hide behavior behind namespaces and can change meaning with imports. Use them when they serve the wider C# community. Markdown: https://matlus.com/writing/extension-methods-no-thank-you.md
- [Factory Pattern: The Enabler of Polymorphism](https://matlus.com/writing/factory-pattern/): A Factory selects and constructs a member of a class family from meaningful input, letting clients use the shared contract while the Factory owns recurring implementation choices. Markdown: https://matlus.com/writing/factory-pattern.md
- [The Configuration Provider: An Abstraction With Roles and Responsibilities](https://matlus.com/writing/configuration-provider-design-pattern/): A Configuration Provider hides the source, returns typed settings, validates required values, and reports useful errors. Composed providers let each system select its settings. Markdown: https://matlus.com/writing/configuration-provider-design-pattern.md
- [Factory Method Pattern: The Most Beautiful Pattern We Lost](https://matlus.com/writing/factory-method-pattern/): Factory Method lets consumer subclasses choose dependencies through an overridable creation hook. C# member managers and Windows Forms show its two class families, distinguishing it from a Factory. Markdown: https://matlus.com/writing/factory-method-pattern.md

## PWI chapters

- [Architecture with Intent](https://matlus.com/pwi/architecture-with-intent/): Layers, boundaries, and where responsibility belongs.
- [Programming with Intent](https://matlus.com/pwi/programming-with-intent/): Classes, methods, naming, and the shape of everyday code.
- [Programming to Exceptions](https://matlus.com/pwi/programming-to-exceptions/): Failure as a designed path rather than an afterthought.
- [Architecture Layers](https://matlus.com/pwi/architecture-layers/): published examples.
  - [Architecture Layers (csharp)](https://matlus.com/pwi/architecture-layers/csharp/): Structure communicates intent: strict layers from Domain Facade to Gateway, internal by default with a public surface the compiler enforces, and folder depth that marks each class's level of abstraction. Markdown: https://matlus.com/pwi/architecture-layers/csharp.md
  - [Architecture Layers (python)](https://matlus.com/pwi/architecture-layers/python/): Structure communicates intent: strict layers from Domain Facade to Gateway, a public surface declared in the boundary __init__.py, and folder depth that marks each class's level of abstraction. Markdown: https://matlus.com/pwi/architecture-layers/python.md
- [Class Design](https://matlus.com/pwi/class-design/): published examples.
  - [Class Design (csharp)](https://matlus.com/pwi/class-design/csharp/): Internal by default, behavior-only classes against state-only types, the two sanctioned uses of interfaces, and closing concrete descendants. Markdown: https://matlus.com/pwi/class-design/csharp.md
  - [Class Design (python)](https://matlus.com/pwi/class-design/python/): Two kinds of class and why that separation holds, no inheritance for extension, and naming conventions for polymorphic types. Markdown: https://matlus.com/pwi/class-design/python.md
- [Method Design](https://matlus.com/pwi/method-design/): published examples.
  - [Method Design (csharp)](https://matlus.com/pwi/method-design/csharp/): Explicit visibility, why public members are never virtual, orchestration over implementation, and return contracts that state their cardinality. Markdown: https://matlus.com/pwi/method-design/csharp.md
  - [Method Design (python)](https://matlus.com/pwi/method-design/python/): Pure and autonomous methods, why public methods orchestrate rather than implement, consistent abstraction levels, and the split between actions and queries. Markdown: https://matlus.com/pwi/method-design/python.md
- [Naming Conventions](https://matlus.com/pwi/naming-conventions/): published examples.
  - [Naming Conventions (csharp)](https://matlus.com/pwi/naming-conventions/csharp/): Deriving names rather than inventing them, domain suffixes over indices, the Async exception, and why Retrieve and Search choose different failure contracts. Markdown: https://matlus.com/pwi/naming-conventions/csharp.md
  - [Naming Conventions (python)](https://matlus.com/pwi/naming-conventions/python/): Naming a thing for what it is: variables named after their type, methods that state the domain outcome, and why inventing a fresh name at each site is where wrong names come from. Markdown: https://matlus.com/pwi/naming-conventions/python.md
- [Validation and Exception Handling](https://matlus.com/pwi/validation-exception-handling/): published examples.
  - [Validation and Exception Handling (csharp)](https://matlus.com/pwi/validation-exception-handling/csharp/): Where validation belongs and where it does not, exception design that fails fast and visibly, message quality, and logging that preserves the failure. Markdown: https://matlus.com/pwi/validation-exception-handling/csharp.md
  - [Validation and Exception Handling (python)](https://matlus.com/pwi/validation-exception-handling/python/): Lock the front door and the back doors, fail fast and visibly, exception messages that carry diagnostic context, and a logging policy that does not swallow failure. Markdown: https://matlus.com/pwi/validation-exception-handling/python.md
- [Type Annotations](https://matlus.com/pwi/type-annotations/): published examples.
  - [Type Annotations (python)](https://matlus.com/pwi/type-annotations/python/): Annotations as intent rather than decoration: None used deliberately, dictionaries kept out of method boundaries, and capability types that tell the truth. Markdown: https://matlus.com/pwi/type-annotations/python.md
- [LINQ Query Semantics](https://matlus.com/pwi/linq-query-semantics/): published examples.
  - [LINQ and Query Semantics (csharp)](https://matlus.com/pwi/linq-query-semantics/csharp/): A query does not run when you write it, and calling it twice may not give the same answer. Deferred execution, materialization, terminal operators, and untranslatable queries. Markdown: https://matlus.com/pwi/linq-query-semantics/csharp.md

## Acceptance Testing

Functional acceptance testing at the boundary, and the surrounding discipline.
This is the Verification with Intent pillar, surfaced at top level.


## Topics

- [Architecture](https://matlus.com/tags/architecture/): How a system is divided into layers, where each responsibility belongs, and what may legitimately depend on what.
- [Naming](https://matlus.com/tags/naming/): Choosing names that state what a thing is, and keeping those names stable as a value moves through a system.
- [Method Design](https://matlus.com/tags/method-design/): Visibility, return contracts, abstraction levels, and the difference between a method that acts and one that answers.
- [Class Design](https://matlus.com/tags/class-design/): Separating behavior from state, deciding what may be inherited, and keeping types honest about what they hold.
- [Testing](https://matlus.com/tags/testing/): Which layer proves what, how tests are arranged, and what a passing test is actually evidence of.
- [Acceptance Testing](https://matlus.com/tags/acceptance-testing/): Exercising a system through its front door as a black box, with attention to where test data comes from and what keeps a scenario true over time.
- [Error Handling](https://matlus.com/tags/error-handling/): Treating failure as a designed path: validation at boundaries, exception translation, and what a caught exception obliges you to do.
- [Data Access](https://matlus.com/tags/data-access/): Reaching a store without letting its shape leak upward. Language-independent guidance, currently illustrated in Python.
- [LLM Systems](https://matlus.com/tags/llm-systems/): Designing processors, engines, and gateways that call language models, and keeping that machinery testable.
- [Python](https://matlus.com/tags/python/): Material specific to Python, or illustrated with Python examples.
- [C#](https://matlus.com/tags/csharp/): Material specific to C#, or illustrated with C# examples.
- [TypeScript](https://matlus.com/tags/typescript/): Material specific to TypeScript, including this site’s own build.
- [AI-Assisted Development](https://matlus.com/tags/ai-assisted-development/): Working with coding agents: what to delegate, how to review the result, and where the failure modes cluster.
- [Verification](https://matlus.com/tags/verification/): Establishing that required work actually happened, rather than accepting a confident report that it did. Coverage, completion, and what evidence supports a claim.
- [Agent Orchestration](https://matlus.com/tags/agent-orchestration/): Coordinating multiple model workers: who decides what, what each one may see, what runs concurrently, and what stops a run.
- [Code Review](https://matlus.com/tags/code-review/): Turning written guidance into rules a reviewer can apply consistently, by machine or by hand.
- [Public Surface](https://matlus.com/tags/public-surface/): The set of types a component exposes to its callers. Everything a caller can receive, pass or must catch belongs on it, and everything else stays internal, so the interior can change without breaking anyone.
- [Levels of Abstraction](https://matlus.com/tags/levels-of-abstraction/): Arranging classes by altitude, so each level states what happens and delegates how to the level below. A class’s depth in the folder tree shows its level, and dependencies run one level down.
- [Service Interface Layer](https://matlus.com/tags/service-interface-layer/): The thin host layer, such as a web API, CLI, worker or cloud function, that connects the outside world to a system. It translates transport input and forwards it to the domain, which must not depend on the host.
- [Design Patterns](https://matlus.com/tags/design-patterns/): Named, reusable solutions to recurring design problems, from the classic catalogue and from this body of work, such as the Domain Facade, the Service Locator and the Gateway.
- [Domain Facade](https://matlus.com/tags/domain-facade/): The single public entry point to a domain. It holds no logic of its own, forwards each business operation to a Manager, and hides every internal layer from callers.
- [Service Locator](https://matlus.com/tags/service-locator/): A narrow factory that creates only what must be swappable, such as configuration, loggers and transport handlers, so tests can substitute them. Only the Manager uses it, and only during construction.
- [Configuration Provider](https://matlus.com/tags/configuration-provider/): A typed wrapper over raw configuration that reads and validates settings eagerly and returns typed settings objects. Only the Manager uses it, and it passes values downstream, never the provider.
- [Gateway Pattern](https://matlus.com/tags/gateway-pattern/): A domain-owned boundary to an external service. It presents business-shaped operations and models, and keeps provider types, resource models and failure translation behind it as one deletable unit.
- [Data Manager](https://matlus.com/tags/data-manager/): The component that owns a domain’s whole conversation with a data store. It presents business-shaped operations and keeps store technology, command construction and fault translation behind its seam.
- [Strategy Pattern](https://matlus.com/tags/strategy-pattern/): Selecting one of several interchangeable behaviors through a common role.
- [Delegates](https://matlus.com/tags/delegates/): Using C# delegates to pass behavior and compare that choice with named strategy classes.
- [Composition Over Inheritance](https://matlus.com/tags/composition-over-inheritance/): Building capabilities from collaborating objects while keeping inheritance narrow and deliberate.
- [Dependency Injection](https://matlus.com/tags/dependency-injection/): Passing collaborators into objects and deciding which dependencies callers should control.
- [Factory Pattern](https://matlus.com/tags/factory-pattern/): Creating the right implementation behind a focused construction boundary.
- [Factory Method](https://matlus.com/tags/factory-method/): A creation hook on a consumer base class that subclasses override to choose a dependency from another class family.
- [Polymorphism](https://matlus.com/tags/polymorphism/): Using a shared contract to work with different implementations without making callers name their concrete types.
- [Library Boundaries](https://matlus.com/tags/library-boundaries/): Contracts that let a system request capabilities in its own terms while containing a library’s calls, types, and failure conventions.
- [Model Design](https://matlus.com/tags/model-design/): Defining data types so required fields, genuine absence, and distinct variants are clear to consumers.
- [Template Method](https://matlus.com/tags/template-method/): Defining an operation in a base type while subclasses provide selected steps.
- [Extension Methods](https://matlus.com/tags/extension-methods/): C# methods called as if they belong to a type, and their effect on discoverability and meaning.
- [Data Transfer Objects](https://matlus.com/tags/data-transfer-objects/): Immutable data carriers that keep state separate from the behavior operating on it.
- [Type Casting](https://matlus.com/tags/type-casting/): Choosing casts and type checks according to whether a mismatch is expected or a defect.
- [Mocking](https://matlus.com/tags/mocking/): Replacing collaborators in tests and evaluating the effect on coupling and regression coverage.
- [Test Driven Development](https://matlus.com/tags/test-driven-development/): Using tests to establish behavior before implementation and preserving them through design changes.
- [Interfaces](https://matlus.com/tags/interfaces/): C# interface roles, their costs, and when a consumer needs a narrow capability.
- [Interface Segregation](https://matlus.com/tags/interface-segregation/): Presenting each consumer with only the operations it needs.
- [Boundary Validation](https://matlus.com/tags/boundary-validation/): Checking untrusted input and output at system boundaries while keeping internal flows clear.
- [Jev](https://matlus.com/tags/jev/): TypeSafe AI’s System One model for typed judgments about supplied text. Choice, Score, and Noul support bounded semantic decisions.
- [Model Evaluation](https://matlus.com/tags/model-evaluation/): Measuring model decisions on representative labeled cases, including error costs, calibration, thresholds, abstention, and performance after changes.
- [Speculative Fan-Out](https://matlus.com/tags/speculative-fan-out/): Asking independent questions about shared state in one request, including answers that some later routes will not use.
- [Confidence-Gated Routing](https://matlus.com/tags/confidence-gated-routing/): Using a model’s answer and tested confidence thresholds to choose between automatic action, another process, and human review.
- [Composite Scoring](https://matlus.com/tags/composite-scoring/): Scoring separate semantic dimensions and combining them with explicit weights to support a decision.
- [Intent Routing](https://matlus.com/tags/intent-routing/): Classifying a request’s intent to choose a handler, such as ordinary code, a specialist model, or a person.