Home on Brian Faust

A Command Bus Must Pay for Its Indirection

Tue, 21 Jul 2026 00:00:00 +0000

Four Laravel routes handle two commands in the reproducible fixture. Two routes inject typed handlers. Two inject Laravel’s dispatcher. All four return 204, and both call graphs leave the same SQLite rows behind.

Then one line disappears from the dispatcher’s handler map. The bus route still resolves its controller, constructs CancelOrder, and enters the pipeline. It returns 500 without selecting a handler. The direct controller has no equivalent registry entry to lose because its constructor already names DirectCancelOrderHandler.

A Composition Root Makes Choices Visible

Tue, 21 Jul 2026 00:00:00 +0000

Remove the ProductPrices binding from a Laravel service provider, then ask the container for QuoteProduct. Laravel refuses to construct it:

Target [App\Application\ProductPrices] is not instantiable while building
[App\Application\QuoteProduct].

Move the same lookup into QuoteProduct::execute() and construction succeeds. The missing dependency does not become visible until a quote request reaches that line. The application object looks simpler because its constructor says nothing. Its object graph is not simpler; part of the graph has moved into method code and configuration.

A Hexagon Is Not a Directory Layout

Tue, 21 Jul 2026 00:00:00 +0000

A Laravel controller calls a catalogue API, reads price_cents, and returns a quote. Moving that HTTP code into Application/QuoteProduct.php makes the controller thinner. It also leaves the application service coupled to Laravel’s HTTP client, the provider URL, and the provider’s JSON.

The tree looks more architectural. The source dependencies have not moved.

That difference becomes visible when the catalogue replaces price_cents with price.amount_minor. A folder name cannot decide where the resulting change lands. A useful hexagonal boundary can: application policy defines the conversation it needs, while an outside adapter owns the provider mechanism.

A Mock Fortress Tests a Call Script

Tue, 21 Jul 2026 00:00:00 +0000

Two tests produce the same checkout quote. One builds five Mockery doubles, specifies every argument, fixes their global call order, and makes a serializer mock return the expected JSON. The other resolves the use case through Laravel’s container, replaces one HTTP catalogue, and asserts the JSON emitted by the real policies and serializer.

Both are green. That tells us they agree with today’s code. It does not tell us what either test will reject tomorrow.

A Pull Request Is a Review Narrative, Not a Template

Tue, 21 Jul 2026 00:00:00 +0000

Most pull-request templates start with good intentions and end as paperwork.

They ask for a summary, testing instructions, screenshots, a ticket, a risk assessment, a deployment plan, a rollback plan, and twelve checkboxes. A small change answers half of them with “not applicable.” A large change fills them with links. The template is complete, yet the reviewer still has to reverse engineer the actual decision from the diff.

The failure is not Markdown. It is treating the presence of headings as proof that communication happened.

A Queued Command Changes the Contract

Tue, 21 Jul 2026 00:00:00 +0000

Send the same payment-capture request through two Laravel routes.

The synchronous route returns 204 after the provider has created charge ch_001 and the order records that reference. When the provider returns 503, the HTTP request returns 500 and the order remains unpaid.

The queued route returns 202 while the order is still unpaid and the provider ledger is empty. Its response contains an operation URL. Cancel the order before a worker starts and that operation later becomes refused; the provider is never called.

A Surviving Mutant Is a Question, Not a Score

Tue, 21 Jul 2026 00:00:00 +0000

Two PHPUnit suites are green. The first checks a known product. The second also checks that a missing product throws ProductNotFound.

Run two mutations against them. The extra assertion kills the missing-exception defect, exactly as intended. Yet a 100% mutation-score gate rejects both suites. The stronger suite finishes at 50% because a second mutation changes no behavior for any input the method accepts.

The gate has calculated its number correctly. It has not interpreted the survivor.

A Valid Command Can Still Be Refused

Tue, 21 Jul 2026 00:00:00 +0000

Send this cancellation request to two orders:

{
 "reason": "customer_request"
}

The placed order returns 204 and becomes cancelled. The shipped order returns 409 and remains shipped. Both requests pass the same Laravel Form Request.

Change the reason to unknown and the result is different again: Laravel returns 422 before the controller constructs a command. Three requests crossed two different decision boundaries. Calling one result “valid” and the others “invalid” hides the part of the system which made each decision.

An Interface Does Not Make a Fake Substitutable

Tue, 21 Jul 2026 00:00:00 +0000

An HTTP product catalogue and an in-memory fake both implement this interface:

interface ProductCatalogue
{
 /** @throws ProductNotFound */
 public function priceCents(string $sku): int;
}

Both return 10000 for CHAIR-BLACK. Both make the checkout test green. Both pass PHP’s signature checks.

Now seed one divergence. When the product is absent, the HTTP adapter throws ProductNotFound while the fake returns zero. The interface remains satisfied, and the familiar checkout test still passes because it never asks for a missing SKU.

Choose the Test Boundary from the Defect

Tue, 21 Jul 2026 00:00:00 +0000

Four test boundaries protect the same reservation flow. Then four defects arrive:

a quantity of zero becomes valid;
a database migration loses a uniqueness constraint;
an inventory provider renames available to stock; and
browser JavaScript submits an empty string instead of the entered quantity.

Calling all four tests “feature tests” would tell us almost nothing. Putting them into a pyramid would tell us how many tests we hope to own, but not which one can catch each defect.

Coverage Tells You What Ran, Not What Your Tests Would Catch

Tue, 21 Jul 2026 00:00:00 +0000

Here are two PHPUnit suites for the same shipping-fee rule. Both report 100% line coverage. Both also report 100% branch and path coverage. One suite lets an off-by-one defect escape; the other catches it.

Nothing is wrong with the coverage report. The mistake is asking it a question it cannot answer.

Coverage can tell us which executable structure a test run visited. It cannot tell us whether the chosen inputs and assertions would notice a defect that matters. The distinction sounds modest. It changes how a coverage target should be used.

Intent Pull Requests

Tue, 21 Jul 2026 00:00:00 +0000

Abstract

The Intent Pull Requests Specification defines what a pull request must communicate before people or automation decide whether to integrate it. A pull request is a review artifact: it describes the complete proposed result, why that result is needed, how the implementation achieves it, why that approach was selected, what it affects, and what evidence supports its claims.

A pull request resembles a small changelog because both explain change. Their audiences and timing differ. A pull request helps reviewers decide whether a proposal should become history. A changelog helps consumers understand history that was released.

Prepare an Intent Pull Request

Tue, 21 Jul 2026 00:00:00 +0000

This skill applies the Intent Pull Requests Specification. It turns a complete branch diff, Project Profile, and verified decision sources into a review-ready title, body, and portable record without opening a remote pull request or inventing claims.

Install

Download the complete skill package or copy and run:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
curl -fsSL https://vacua.dev/skills/prepare-intent-pull-request/bundle.tar.gz \
 | tar -xz -C "${CODEX_HOME:-$HOME/.codex}/skills"

Invoke

$prepare-intent-pull-request prepare this branch for review

Read the raw SKILL.md.

Commit with Intent

Mon, 20 Jul 2026 00:00:00 +0000

This skill combines repository-safe Git packaging with the Intent Commits Specification. It keeps type, scope, impact, migration, affected release units, and changeset links evidence-bound. After committing, it uses ACK’s repository-aware link validator to detect missing or contradictory Intent Changesets decisions.

It composes the existing commit-changes safety workflow instead of replacing explicit staging, secret checks, line-length validation, or commit verification.

Install

Download the complete skill package or copy and run:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
curl -fsSL https://vacua.dev/skills/commit-with-intent/bundle.tar.gz \
 | tar -xz -C "${CODEX_HOME:-$HOME/.codex}/skills"

Invoke

$commit-with-intent commit the staged changes using our ACK profile

The skill returns NEEDS_INPUT instead of inventing scope, release impact, migration guidance, issue references, or changeset identifiers.

Configure an Intent Project

Mon, 20 Jul 2026 00:00:00 +0000

This skill creates or reviews the Project Profile shared by Intent Commits, Intent Changesets, Intent Changelog, Release Manifests, and ACK. It discovers real release units and streams instead of duplicating policy in each tool.

Install

Download the complete skill package or copy and run:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
curl -fsSL https://vacua.dev/skills/configure-intent-project/bundle.tar.gz \
 | tar -xz -C "${CODEX_HOME:-$HOME/.codex}/skills"

Invoke

$configure-intent-project configure ACK for this monorepo

Read the raw SKILL.md.

From Commit to Changelog: An Intent-Aware Release Pipeline

Mon, 20 Jul 2026 00:00:00 +0000

Most release processes postpone the important questions.

A developer commits a change. A pull request describes some of it. Somebody adds a changeset because CI demands a file. Much later, another person opens an Unreleased section and tries to reconstruct what users need to know.

The tools are connected by chronology, but not by meaning.

That is why release day becomes an archaeological exercise. The diff still exists, but the reason, audience, migration path, affected application, and release judgment have been scattered across Git, an issue tracker, review comments, and somebody’s memory.

Intent Changelog

Mon, 20 Jul 2026 00:00:00 +0000

Abstract

The Intent Changelog Specification defines a structured release ledger for software projects. It treats an unreleased release as a real release whose publication date is not yet known, rather than as an inbox of uncategorized changes.

Each release record belongs to one release unit and contains complete, categorized entries. An entry records what changed, why it changed, who needs to know, its release impact, migration guidance, and its provenance. Projects may define their own change types without forcing unrelated changes into a fixed universal taxonomy.

Intent Changesets

Mon, 20 Jul 2026 00:00:00 +0000

Abstract

The Intent Changesets Specification defines a small, structured artifact for one independently understandable release decision. A changeset explains what consumers will experience, why the change exists, which release units it affects, and what release impact each unit should receive.

Intent Changesets sits between commit history and release history:

Intent Commits Specification messages record the intent of atomic Git changes and link to a changeset with a Changeset trailer;
Intent Pull Requests records may link reviewed integration context to one or more changesets;
an Intent Changesets record combines one or more commits or pull requests into one releasable decision; and
Intent Changelog Specification entries consume that decision into the canonical release ledger.

A changeset is not a release, changelog, pull request template, version-bump command, or mandatory file for every commit. Projects define which changes are noteworthy enough to require one.

Intent Commits

Mon, 20 Jul 2026 00:00:00 +0000

Abstract

The Intent Commits Specification is a lightweight protocol for commit messages. It preserves the familiar type(scope): description header while separating four concerns that are often conflated:

the kind of work performed;
the area affected;
the release impact requested; and
the information consumers need to adopt or reverse the change.

Intent Commits uses Git-compatible trailers for machine-readable metadata. A commit type classifies the work; it does not determine a version increment by itself.

Intent Commits: Commit Types Are Not Release Decisions

Mon, 20 Jul 2026 00:00:00 +0000

Conventional Commits solved a real problem. It gave teams a small shared grammar for a part of software development that had mostly been left to taste:

feat(auth): support passkeys

That line is easy to write, easy to scan, and easy to parse. It is a much better foundation than histories full of changes, updates, and fix stuff. It can drive changelogs, release automation, and navigation through an unfamiliar codebase.

Maintain a Release Manifest

Mon, 20 Jul 2026 00:00:00 +0000

This skill applies the Release Manifest Specification to record and verify what was actually published. It distinguishes repository-level proof from remote artifacts that were not fetched or verified.

Install

Download the complete skill package or copy and run:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
curl -fsSL https://vacua.dev/skills/maintain-release-manifest/bundle.tar.gz \
 | tar -xz -C "${CODEX_HOME:-$HOME/.codex}/skills"

Invoke

$maintain-release-manifest verify the worker 1.18.3 release

Read the raw SKILL.md.

Maintain an Intent Changelog

Mon, 20 Jul 2026 00:00:00 +0000

This skill applies the Intent Changelog Specification. It keeps unreleased records complete, consumes changeset targets, validates and renders them with ACK, and enforces date-only publication. Canonical generation carries verified commit provenance through changesets into the correct release-unit records.

It does not turn Unreleased into an editorial inbox or use commit-derived Markdown as the canonical release ledger.

Install

Download the complete skill package or copy and run:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
curl -fsSL https://vacua.dev/skills/maintain-intent-changelog/bundle.tar.gz \
 | tar -xz -C "${CODEX_HOME:-$HOME/.codex}/skills"

Invoke

$maintain-intent-changelog add this change to the worker release record

Read the raw SKILL.md.

Maintain an Intent Changeset

Mon, 20 Jul 2026 00:00:00 +0000

This skill applies the Intent Changesets Specification. It helps an agent decide whether a noteworthy change needs a changeset, link relevant commits, and consume each target into the correct changelog release record.

One changeset represents one release decision—not one commit or pull request. The skill uses ACK to validate the shared profile, enforce identifier uniqueness, create canonical pending records, validate commit links, consume every release-unit target, and gate publication until consumption is complete.

Project Profile

Mon, 20 Jul 2026 00:00:00 +0000

Abstract

The Project Profile Specification defines one versioned YAML document that connects Intent Commits, Intent Pull Requests, Intent Changesets, Intent Changelog, and Release Manifest records to a repository’s actual boundaries and policies.

The other specifications deliberately avoid prescribing one universal set of types, scopes, release units, audiences, channels, or versioning rules. Without a portable profile, however, two implementations cannot resolve those project-defined values in the same way. This specification makes that shared policy explicit.

Release Manifest

Mon, 20 Jul 2026 00:00:00 +0000

Abstract

The Release Manifest Specification defines an immutable evidence record for one published release of one release stream. It answers a question that commits, changesets, and changelogs deliberately do not: what exactly shipped?

A manifest binds the release identity to:

the source repository, commit, and tag;
the published Intent Changelog record and its digest;
the release decisions represented by that record;
every declared artifact and its cryptographic digest; and
optional supply-chain evidence such as an SBOM or build attestation.

A manifest is not a deployment plan, package-manager command, mutable release dashboard, or substitute for a changelog. It records a completed publication boundary in a form people, CI, and downstream automation can verify.

Unreleased Is Not a Junk Drawer

Mon, 20 Jul 2026 00:00:00 +0000

Keep a Changelog got one foundational idea exactly right: a changelog is for people. It should explain noteworthy changes instead of dumping commit history into a Markdown file.

That principle is sound. The document model built around it is where the frustration begins.

The problem becomes most visible under this heading:

## Unreleased

The failure mode is easy to recognize. Everything remotely noteworthy goes there while work is in progress. When a release approaches, somebody finally decides which application the entries belong to, rewrites their summaries, moves them under categories, removes internal noise, adds migration notes, and tries to reconstruct why half of the changes mattered.

EventStorming Finds Disagreement Before It Finds Services

Sun, 19 Jul 2026 00:00:00 +0000

Ask sales, support, finance, and engineering when an order becomes cancelled and the answers may sound compatible until they share a wall.

Sales says cancellation happens when the customer asks. Support says it happens after a case is approved. Finance says a paid order remains active until the refund clears. Engineering points to a cancelled_at column written before the payment provider responds.

That disagreement is not workshop noise. It is the model.

Shared Kernel or Published Language: Choose Where Coordination Lives

Sat, 18 Jul 2026 00:00:00 +0000

Billing and fulfilment both use the word “order.” Sharing an Order class looks like the obvious way to keep them consistent.

Then billing adds credit notes, tax evidence, and settlement state. Fulfilment adds picking waves, split shipments, and packing exceptions. The shared class either accumulates both models or becomes a negotiation every time one team changes it.

Integration always creates coordination. A Shared Kernel and a Published Language place that coordination in different locations. The first shares a small piece of model and requires teams to change it together. The second shares a versioned language at the boundary and lets each side translate it into its own model.

A Process Manager Remembers What the Queue Cannot

Fri, 17 Jul 2026 00:00:00 +0000

An order is paid at 10:00. Inventory is reserved at 10:01. The warehouse does not respond until 14:30. Shipping fails the next morning, after two worker deployments and a payment-provider timeout.

No request, transaction, or queue worker owns that whole timeline. Chaining jobs can move execution from one step to the next, but the queue does not know whether the business process is waiting, complete, compensating, or stuck.

A Process Manager exists to remember that state and decide what should happen when a relevant message arrives. Its value begins where call-stack control ends.

CQRS Starts When Reads Need a Different Model

Thu, 16 Jul 2026 00:00:00 +0000

An order-details page needs customer name, payment status, shipment progress, line totals, tax labels, and the latest support case. The write model needs to protect payment, cancellation, and fulfilment invariants.

Trying to make one Eloquent graph serve both jobs creates a familiar mess: relationships exist for screen composition, write methods expose persistence concerns, and every request loads a different subset of a model that is never quite complete.

That tension can justify different read and write models. It does not automatically justify two databases, an event store, a command bus, or eventual consistency. CQRS is the model split; the infrastructure is a separate set of decisions.

A Repository Is a Domain Collection, Not an ORM Wrapper

Wed, 15 Jul 2026 00:00:00 +0000

This interface appears in many Laravel codebases:

interface Repository
{
 public function all(): Collection;
 public function find(int $id): ?Model;
 public function create(array $attributes): Model;
 public function update(int $id, array $attributes): Model;
 public function delete(int $id): bool;
}

It hides the word Eloquent and preserves everything else about Eloquent’s world: models, attribute arrays, record IDs, and CRUD operations. Callers still need to know which fields are writable, which relationships are loaded, and which operations preserve domain rules.

That is not a useful persistence boundary. It is a smaller, less capable ORM.

Entity, Value Object, Aggregate, Model, DTO: Name the Role

Tue, 14 Jul 2026 00:00:00 +0000

An Order can be an Eloquent model, a domain entity, an aggregate root, an API resource, and a row in a database. Those statements describe different roles. Treating them as synonyms makes design conversations sound precise while each person is discussing a different boundary.

DDD’s modelling vocabulary becomes useful through concrete questions:

Does this thing remain the same when its attributes change?
Is equality based on identity or on all constituent values?
Which rules must be consistent before one transaction commits?
Is this shape for domain behavior, persistence, or transfer?

The labels follow those answers.

Strategy Chooses How; Command Records What to Do

Mon, 13 Jul 2026 00:00:00 +0000

Two PHP types can have almost identical shapes and still solve different problems:

interface ShippingRate
{
 public function quote(Shipment $shipment): Money;
}

interface ApplicationCommand
{
 public function execute(): void;
}

Both hide behavior behind a method. Both can be injected and tested. Their surface similarity makes “algorithm versus action” an easy first distinction, but it is not enough for application architecture.

The more useful distinction appears after execution fails. A strategy is a collaborator used while another operation is already in progress. A command represents work that can acquire its own lifecycle. Once work must be queued, retried, deduplicated, authorized, or audited independently, it is no longer merely a choice of implementation.

A Null Object Should Mean Nothing Happened

Sun, 12 Jul 2026 00:00:00 +0000

A missing coupon is not an error. Checkout should continue, the discount should be zero, and callers should not care whether a coupon was supplied.

A missing payment gateway is different. Pretending that a charge succeeded would corrupt the order workflow. Even doing nothing would turn a deployment mistake into a plausible-looking transaction.

Both dependencies can be typed as nullable, but only one has an honest neutral behavior. That is the boundary for the Null Object pattern: use it when absence means “perform the same operation with no effect,” not whenever an if statement looks untidy.

Tell, Don't Ask Means Keep the Decision with the State

Sat, 11 Jul 2026 00:00:00 +0000

This controller looks reasonable:

if ($order->status === OrderStatus::Draft && $order->lines->isNotEmpty()) {
 $order->status = OrderStatus::Placed;
 $order->placed_at = now();
 $order->save();
}

It reads state, makes a decision, mutates more state, and persists the result. The problem begins when an API controller, an import command, and an admin action each reproduce that sequence with slightly different conditions.

“Tell, don’t ask” is useful when it moves a decision back to the object that owns the relevant state. It is not a ban on queries, getters, or conditional logic. The smell is asking an object for its internals so another object can enforce its rules.

The Law of Demeter Is About Knowledge, Not Dots

Fri, 10 Jul 2026 00:00:00 +0000

$order->customer->primaryAddress->city looks harmless. It may even execute the right number of queries. The problem appears six months later, when an order can have several delivery destinations and every caller has encoded the old path to a city.

This is the useful part of the Law of Demeter: keep structural knowledge near the object or module that owns the structure. Counting arrows is a poor substitute for that reasoning. A fluent query builder can have a long chain without crossing a boundary; a single getter can expose an object that the caller has no business navigating.

Composition Over Inheritance Is a Decision, Not a Rule

Thu, 09 Jul 2026 00:00:00 +0000

“Favor composition over inheritance” is useful advice right up to the point where it becomes a reflex. Replacing every parent class with an interface and a service-container binding does not make a design better. It merely exchanges one form of coupling for another.

The decision is about how behavior is allowed to vary.

Inheritance fixes variation into a type hierarchy. Composition puts variation behind collaborators that can change independently. When tax, discounts, shipping, and payment rules evolve along different axes, forcing them into one family tree is expensive. When a subtype genuinely preserves a small, stable parent contract, inheritance may be the clearest tool available.

Dependency Inversion Lets Policy Own the Boundary

Wed, 08 Jul 2026 00:00:00 +0000

This class uses constructor injection and still points in the wrong direction:

final readonly class QuoteShipment
{
 public function __construct(private GuzzleHttp\Client $http) {}

 public function handle(Shipment $shipment): Money
 {
 $response = $this->http->post('/carrier/rates', [
 'json' => CarrierPayload::fromShipment($shipment),
 ]);

 return Money::EUR(
 json_decode($response->getBody(), true)['price_cents'],
 );
 }
}

The dependency is visible and testable, but the application use case knows an HTTP client, carrier endpoint, payload, response shape, and currency assumption. Replacing new Client() with an injected client improved assembly; it did not protect policy from the detail.

Interfaces Belong to Their Clients

Tue, 07 Jul 2026 00:00:00 +0000

A carrier integration often begins with one generous interface:

interface Carrier
{
 public function quote(Shipment $shipment): ShippingQuote;
 public function buyLabel(Shipment $shipment): Label;
 public function cancelLabel(LabelId $labelId): void;
 public function track(TrackingNumber $number): TrackingStatus;
 public function bookPickup(PickupRequest $request): Pickup;
 public function closeManifest(LocalDate $date): Manifest;
}

The checkout page needs only quote(). A tracking job needs only track(). One carrier may not support pickups; another may not use manifests. The broad interface makes every consumer and implementation participate in capabilities they do not share.

The Interface Segregation Principle asks for client-specific contracts. It does not demand one method per interface. Split where clients, implementations, or change reasons diverge.

Substitution Is a Behavioral Contract

Mon, 06 Jul 2026 00:00:00 +0000

Both of these classes implement the same interface:

interface InvoiceArchive
{
 public function store(InvoiceId $id, PdfDocument $document): Location;
 public function read(Location $location): PdfDocument;
}

final class NullInvoiceArchive implements InvoiceArchive
{
 public function store(InvoiceId $id, PdfDocument $document): Location
 {
 return Location::from("memory://{$id->value}.pdf");
 }

 public function read(Location $location): PdfDocument
 {
 throw new RuntimeException('Nothing was stored.');
 }
}

PHP accepts the implementation. A client that stores a document and later reads the returned location does not. The method signatures match while the behavioral contract is broken.

The Liskov Substitution Principle is about that gap. Code written against a supertype must continue to work when it receives any subtype. Interfaces, inheritance, fakes, decorators, and adapters all create subtype promises; the principle is not limited to class hierarchies.

Open–Closed Protects Stable Policy from Repeated Variation

Sun, 05 Jul 2026 00:00:00 +0000

The third shipping carrier usually exposes the design more clearly than the first.

With one carrier, a conditional is honest. With three, adding a carrier may require editing quote calculation, label purchase, tracking links, validation, service-provider bindings, and tests. The same variation keeps reopening code that was already working.

The Open–Closed Principle addresses that pattern: establish a stable policy that is closed to this recurring modification while new variants arrive through an explicit extension point. It does not say existing code must never change. It says repeated variation should stop causing shotgun surgery.

Single Responsibility Is About Change, Not Class Size

Sat, 04 Jul 2026 00:00:00 +0000

A class with one public method can still mix pricing policy, PDF layout, storage, and email delivery:

final class SendInvoice
{
 public function handle(Order $order): void
 {
 $tax = $order->subtotal * config('billing.tax_rate');
 $pdf = Pdf::html(view('invoice', compact('order', 'tax'))->render());
 Storage::disk('invoices')->put("{$order->id}.pdf", $pdf);
 Mail::to($order->customer)->send(new InvoiceMail($pdf));
 }
}

Its method count is one. Its reasons to change include tax rules, document presentation, retention, storage infrastructure, and delivery policy. “Do one thing” is too vague to expose that coupling.

The Single Responsibility Principle is more useful as a change rule: group code that changes for the same reason and separate code that changes for different reasons. Robert Martin’s clarification of SRP connects those reasons to the people or business functions requesting them.

About

Mon, 01 Jan 0001 00:00:00 +0000

Hello! I’m Brian, a self-taught senior software engineer focused on developer experience and tooling. I build open-source packages and practical systems that remove friction from everyday engineering work.

Over the past two decades, I’ve worked as a freelance engineer, independent contributor, and consultant for teams around the world. My work often begins where a product, platform, or engineering organization has become difficult to change. I help clarify the technical direction, renew the foundations, and leave teams with systems they can confidently own.

Projects

Mon, 01 Jan 0001 00:00:00 +0000

Open-source tools I build to make engineering work more explicit, dependable, and easier to operate.

Thoughts

Mon, 01 Jan 0001 00:00:00 +0000

Notes on design, code, and the details that make software feel considered.