How we build, the engineering handbook in public

Brilliant Systems publishes its delivery method so clients can read it, quote it back, and check whether we kept it.

Most firms treat their delivery method as proprietary. It appears in a pitch deck as five words on a diagram. Then it is never written down anywhere a client could hold them to it.

We publish ours because a method only works as a commitment when you can inspect it. You should be able to read it before signing, quote it back during delivery, and check whether we did it at the end. A method nobody can check is only a description of intentions.

This is the whole thing.

The method starts before the contract is signed

Before there is a contract, we want the useful parts in writing. That means an engineer looks at the problem early, the constraint is discussed plainly, and the approach can be compared before anyone commits.

The order is simple.

  1. Within one business day, you speak with an engineer. Someone who could work on the project reads what you sent and replies with questions, an initial view, or a straight answer that we are the wrong firm. The reply comes from an engineer rather than an account manager or a qualification call. If the honest answer is that a standard product fits your problem, you get that on day one rather than after a paid discovery phase.
  2. Day two to four, we spend forty-five minutes on the problem. We talk about the constraint rather than presenting credentials. Bring whoever knows why the current system is the way it is, because that person holds the information that decides the estimate. There is no deck.
  3. Within a week, you get a written approach. It says how we would build it, in what order, with a cost and time range and the assumptions those depend on. It is written plainly enough to forward to a board without translation. This is free and useful even if you take it to another supplier.
  4. When you are ready, you get a fixed proposal. Scope, price and milestones are in writing, with the like-for-like comparison against conventional delivery stated beside our number. If we cannot beat it meaningfully, we say so and decline.

During the build, you can see the work

During the build, the commitment becomes visible. You can see the code, run the software early, and read the same weekly position we are working from.

  • You get repository access from day one. This means the actual place where the code is kept, with every commit visible as it happens. It is the actual repository, rather than a demo environment. Clients rarely look, and it changes the relationship that they could.
  • You get a running environment as soon as there is something to run. Usually this happens within the first fortnight. We do it deliberately before it is impressive, because early ugly software surfaces misunderstandings that a polished demo three months in would have hidden.
  • You get a weekly written note. It covers what shipped, what did not, what changed in the estimate, and what we need from you. Three paragraphs, every week, whether or not there is good news. The weeks with bad news are the ones that make the practice worth anything.
  • Change is priced as an increment. Scope changes are normal. What matters is that a change is quoted at the moment it is agreed, visibly, rather than appearing later as a surprise. If we underestimated, that is our error, and you do not pay for it.

Some standards apply to every engagement

Six things are true of every engagement without being asked. They are part of the work, rather than extras that appear if somebody remembers to ask for them.

  • Tests come before the rewrite. We do not replace a system we cannot characterise. Behaviour gets covered first, including behaviour nobody documented and some nobody intended. Then replacement happens in slices.
  • Deployment is reversible. Every release can be rolled back, and the rollback has been executed as a drill rather than assumed to work. Drills routinely find fallback paths that had rotted.
  • Decisions are recorded. An architecture decision record captures every significant choice, including the options rejected and why. In three years that document is worth more than the code it explains.
  • Security runs through the work. Threat modelling happens at design, dependencies are watched continuously, and secrets are never in the repository. There is no security sprint at the end.
  • Documentation is written for a stranger. The runbook is written for someone who has never met us. If your team cannot deploy it without calling, the handover is not finished.
  • The 2am rule applies. If we would not be willing to be woken up for it, we do not ship it. Blunt, and it removes a surprising amount of argument.

Before handover, someone tries to break it

Before handover, an engineer who did not build the system spends a week trying to break it. The review covers load, authentication, data handling, failure modes, and the paths nobody tested because they were obviously fine.

You get the findings. You get all of them, including the ones we did not fix, with the reason. A report with no unfixed findings means the review was not serious.

This occasionally delays a delivery we had committed to a date for. We absorb that, because a red-team week that gets skipped when the schedule is tight is a red-team week that never happens.

AI has a defined role

We are specific about where AI sits because vagueness here is how firms avoid accountability.

What AI does

AI can read a legacy system faster than we can and produce a map we then verify. It can write first drafts of tests, migrations and boilerplate that a person owns. It can review every change before a human does, so review time goes on design rather than typos. It can turn a specification into an evaluation harness, a way of checking whether the specification is being met.

What AI never does

  • It never merges its own work. Every change is approved by a named engineer.
  • It never touches production. Deployment is a human action with a name against it.
  • It never sees client data it does not need. Boundaries are set in writing at the start.
  • It never excuses a defect. If it shipped broken, that is ours, and how it was written is not a mitigation.

At the end, the important assets are yours

At the end, you own the code outright, full intellectual property, in your repository with commit history intact. You also get the documentation, runbook and decision records.

There is no proprietary lock-in. We use mainstream technology throughout, with nothing that requires us specifically. You also get infrastructure as code, so the environment is reproducible if your provider relationship changes.

You also have the right to leave. There is no minimum term on retained work, thirty days notice, and we help you move. Payment disputes are handled commercially and never by withholding what you own.

There are lines we will not cross

Some things are out of bounds for us.

  • Bill for a change we caused.
  • Take work we cannot beat the market on.
  • Put a junior on it and describe them as senior.
  • Hold your code against an invoice.

Each of those costs us money occasionally. Publishing them is what makes them expensive to break, which is the point of publishing.

The method has failed, and the failures changed it

A published method is only credible with the failures attached, so here are three.

The written approach was too optimistic

We produced a one-week approach document for an integration with a third-party system, based on its published API documentation. The documented behaviour and the actual behaviour diverged substantially under production data volumes. The work took roughly 60 percent more effort than quoted and we absorbed it. The method now includes a paid one-day integration probe on anything involving an unfamiliar third party, before a fixed price is offered.

The red-team week got compressed

A delivery date was tight and the review was cut to two days. It found nothing serious. Six weeks later a load-related defect surfaced in production that a full week would very likely have caught. The rule now is that the week is not negotiable and the date moves instead, which has cost us a client relationship since.

The handover did not work

We wrote documentation we thought was thorough. Three months later the client’s team could not deploy a change without calling us, which we had told them would not happen. The runbook described what we did rather than what they needed to do. The supervised period, where their people operate the system while we watch and do not touch it, exists because of that project.

Every one of those produced a change to the method. That is the argument for writing it down: an undocumented process cannot be corrected, only forgotten and rediscovered.

The client side has obligations too

The method has obligations on both sides, and engagements struggle when the client side is not met.

  • Somebody who can decide. We need a person who can settle a scope question within a couple of days. A committee cannot do that. The single largest cause of delay on our projects is waiting for a decision nobody is empowered to make.
  • Access, early. This means systems, credentials, environments, and the person who knows why the odd thing is odd. Every week of delay in getting access is a week added to the end, and it is the item most often underestimated at kick-off.
  • Honesty about the constraint. If the real driver is a board deadline, a compliance date or an internal political situation, telling us shapes the plan. We have built the wrong sequence more than once because nobody mentioned the actual deadline.
  • A named person for acceptance. Someone has to look at what we delivered against the definition of done and say yes or no. Ambiguity here is what turns a fixed-price engagement into a disagreement.

You can test whether a supplier means it

Every firm claims a method. Four questions separate a published commitment from a diagram.

  • Can I read it before signing? If the process only appears in a proposal written for you, it is a description of this project rather than a standard. A standard exists independently of the client.
  • What happens when you underestimate? The most informative question available. A firm that invoices the difference is selling capacity. A firm that absorbs it is selling accountability, and the price reflects that.
  • Show me a red-team report with unfixed findings. Any serious review produces items that were deliberately not addressed, with reasons. A clean report means the review was theatre.
  • What would make you decline this? A supplier who has never turned work down is optimising for revenue rather than outcome, and will take your project regardless of whether it should exist.

We publish the method because it binds us

Three reasons explain why this is public, in increasing order of self-interest.

It saves time. Clients who read this arrive knowing how we work, and the conversations start further along.

It filters. Organisations that want a supplier who bills by the hour and absorbs unlimited direction changes read this and go elsewhere. That is better for both parties than discovering it in month three.

It is also a constraint on us. A published method is one we can be held to by any client, in writing, at any point. That pressure is what makes it worth something, and it is the same reason we publish a fixed price with the conventional comparison beside it rather than a rate.

The full version lives on how we work, the commercial structure on engagement models, and what we commit to on data on the trust centre.

Written by Brilliant Systems

Our engineers write these between projects. If something here is relevant to a decision you are making, we are happy to talk it through without it becoming a pitch.

Certified, partnered and awarded