What a first build should leave behind

Most custom software projects end with a handover: logins, a user manual, a support contract. The system works. Six months later a rule changes, and the enterprise discovers what it was given. It has a system it can use and cannot alter, and the only people who understand it are employed by someone else.

This article is for the CIO or operations head who has been through that once and is sceptical of the next proposal. It sets out what a first build should leave behind besides the software, and how to check for it before signing.

A delivered system and a described operation

There are two things a build can produce.

A delivered system is working software. Screens, reports, a database. It is judged by whether it does what was asked.

A described operation is a written account of how the business runs, precise enough that software can be built from it: what things exist, what happens to them, and what goes wrong. It is judged by whether someone who was not in the project can read it and understand the system.

Every project produces the first. Few produce the second in a form that lasts. Requirements are gathered, turned into code, and then left to age while the code moves on. Within a year the document describes a system that no longer exists, and the real description lives in the code and in the heads of the people who wrote it.

The difference decides who owns the result. If the description is yours, current and readable, any competent team can carry the work on. If it is not, you are tied to whoever holds the knowledge, whatever the contract says about intellectual property.

The three things to have written down

A useful description of an operation has three parts. They are worth asking for by name.

Entities

The things the operation tracks, in the words the floor uses. Not “item” and “document”, but the real nouns.

At a textile processing house that finishes cotton cloth, the nouns include the lot that arrives from a dyeing mill, the gate pass that travels with the truck, the lump of fabric, the grade, and the bale. Each has a definition a new joiner could read: what it is, what identifies it, what it belongs to. A thaan belongs to a lot, and a lot to a gate pass, which is why the thaans in a packed bale can be traced back to the truck they arrived on.

A good test: read the list of entities to a supervisor. If they correct a definition, the list is alive. If they do not recognise the words, it was written in a meeting room.

Events

The things that happen, each named as a plain past-tense fact, with who does it and what it records. “Gross weight recorded.” “Purchase order released.” “Bale dispatched.”

At a multi-plant power producer, which buys biomass fuel for its plants, a vehicle’s visit is a trip that passes six checkpoints: gate entry, quality, gross weight, unloading, tare and exit. Each is an event recorded by the person whose job it is. Written down, the event list is short, and it tells a reader more about the operation than any number of screenshots.

The event list is also the part with the longest life. Screens get redesigned. Reports are added and dropped. The fact that a truck is weighed twice does not change.

Exceptions

The cases that do not follow the normal path, and what is done about each. This is the part most often missing, and it is where most of the operation’s knowledge sits.

Examples of the kind a site visit turns up: a load arrives when the weighbridge is down. A delivery comes in short. Goods go straight from the vendor to the customer and never touch the warehouse. Low-grade material is weighed where everything else is measured. A packed bale is opened and repacked for a different buyer.

For each one, the description should say how it is recognised, who decides, and what the system records. An exception that is listed but has no decided path will come back as a remarks field.

Where the description comes from

It matters how the description was produced, because that predicts whether it is true.

The documented projects behind the examples in this article followed a similar course. Someone went to the site before anything was designed and wrote down what they saw, area by area: the gate, the weighbridge, the folding tables, the stores. The registers, slips and forms in daily use were collected, because they show what the operation actually records. The trade’s own terms were listed with their meanings. A scope was written in plain language, saying what would be built and what would not, and it was revised with the client through several versions as the site visits improved the understanding.

Two habits from those projects are worth copying whoever builds your system.

The scope says what is excluded. A list of what the first build will not do prevents more disputes than any list of what it will.

The specification is corrected when the build departs from it. Builds always depart. A rule turns out differently on the floor, or a step is dropped. Where the written specification was reconciled with what was actually shipped, it remained a description of the real system. Where that is skipped, the document is out of date on the day of go-live.

A specification that is the build

There is a stronger version of this, and it is now practical. If the specification is precise enough, it is not a document that sits beside the build. It is what the build is made from.

When code is written quickly, much of it by AI working inside firm rules, the limiting input is the description: the entities, events, exceptions, roles and permissions. Change the description and the system follows. In that arrangement the specification cannot drift far from the software, because the software is produced from it.

For a buyer, the practical consequence is that the description stops being a courtesy at the end of the project. It is the main asset. Ask to see it during the build, not after.

The day the vendor leaves

A fair way to judge any proposal is to imagine the vendor gone, on good terms, the day after go-live. What can you do?

You should be able to:

Read what the system does. Open the description and find any rule: who can approve a deduction, what happens to a short delivery, how a calculated figure is worked out.
See your own history. Every action that has happened, with who and when, in a form you can query or export. Not only the current balances.
Hand it to someone else. Give the description and the system to another team and have them make a small change without a long discovery phase.
Know who can do what. The roles and permissions written down in one place, not scattered through configuration.
Add the next process. Start a second system for a neighbouring part of the operation, using the same users, roles, approvals and history, and not starting from an empty page.

If the answer to most of these is “we would need to call them”, the build delivered a system and kept the operation.

Questions to ask before signing

Put these to any vendor, including an internal team.

What documents will exist at the end, and can I see an example from a finished project with the client’s details removed?
Who goes to our site, for how long, and before or after the design is drawn?
Will the entities, events and exceptions be listed in our own terms? Show me what that list looks like.
How is the specification kept in step with the system after changes? Who updates it?
Does the scope state what is excluded?
Is the history of what happened stored as a record that cannot be edited, or as current values with a log?
If we wanted a different team to extend this system, what would they need from you, and is it in the contract?
What does the second system reuse from the first? Be specific: users, roles, approvals, reporting, data.
Who on our side will understand the description when you are done, and how will they get there?
What happens after go-live: who makes the first change, and how long does it take?

The answers to 4, 7 and 8 separate vendors most clearly. A vendor whose business depends on you coming back for every change will find them uncomfortable. That is not dishonesty. It is the model, and you should know which model you are buying.

What to check in the first fortnight

You do not have to wait until the end to find out. Early in any build, look for these.

The team has been on the floor, and people there can name who came.
You have been shown a list of exceptions and asked to add to it.
The words in the drafts are your words.
Something has been ruled out of scope in writing.
You have seen the event list for one process, and a supervisor agreed with it.

If none of these has happened by the time screens are being demonstrated, the description is not being written. It will not appear later.

How this is handled in Phlo

Phlo, the framework Jetbro builds on, treats the description as the thing being built. The first build, Phlo Enterprise Systems, starts on your floor and produces a model of your operation: entities, events and exceptions, written down. The system is built from that model, on a foundation where events, roles and permissions, approval chains and reporting already exist. Every action is recorded as an event and nothing is overwritten.

That model and that record are what the second stage rests on. With Phlo Framework, the framework becomes available to you: your own engineers and product people can build the next system on it, or Jetbro can carry on. The terms of that stage are settled in the first conversation, scoped to the engagement. The first build is not a pilot. It is where your operation gets described, and whoever builds next starts from there.