How We Turn a Business Process Into Custom Software
- Most custom software fails at the same point: nobody wrote down the process as it actually runs, only as the owner remembers it in a meeting.
- We start from one narrated day, three non-negotiable business rules, and a hand test of every third-party API before any code is written.
- A working prototype reaches the owner before pricing, and deployment ships with a per-project checklist covering environment variables, backup, rollback and monitoring.
The symptom: the software is finished and the business still runs on the spreadsheet
A common pattern on projects we audit: a company pays for a system, the system goes live, and three months later the operations team is still exporting CSVs and pasting them into a spreadsheet. The developer says the feature exists. The operator says the feature is useless. Both are telling the truth.
You notice this by watching, not by asking. Sit next to the person doing the work for one afternoon and count how many times they leave the new system to do something else. Every time they open a spreadsheet, a chat thread, a personal inbox or a second tab of the old tool, that is a step the software does not model. The symptom is not a missing button. It is a missing decision: the software was built around data entry, and the real work is a sequence of choices with conditions attached.
Other symptoms that point to the same root cause:
- The system has fields nobody fills in, and fields everyone fills in that were not in the original spec.
- Two people maintain the same list in two places, and reconciling them is a weekly task.
- The owner cannot answer "where is order X right now" without messaging someone.
- Reports exist but nobody opens them, because the numbers do not match what the team already knows.
- Integrations break silently. Documents get created twice, or not at all, and nobody notices until a customer complains.
How to diagnose it: interview, rules, and a hand test of every API
The diagnostic is deliberately low-tech and happens before any architecture discussion.
One conversation, one real day. The owner narrates a single working day out loud, in order, from the first task to the last. The rule for the person listening: every time the owner says "then I open the spreadsheet", that becomes a numbered step in a document. No summarising, no grouping, no "and similar tasks". The output is a list of concrete steps in the order they happen, with the tool used at each step. This takes one conversation and produces the real process, not the intended one.
Three rules the business cannot bend. Ask the owner which rules would cause real damage if the software violated them, and write them as full sentences. On a marketplace integration we worked on, one rule was written exactly like this: "a completed order never receives a new outbound document." That sentence is testable. It becomes a database constraint, a guard in the integration worker, and a test case. A vague requirement like "avoid duplicate documents" is none of those things.
Test the third-party APIs by hand before writing a line of code. This is a fixed rule on every integration. Before the first commit, we call the external API with curl or Postman and record what actually comes back: authentication flow, required headers, pagination shape, rate limits, error bodies, and what happens when you send the same request twice. Documentation and reality differ often enough that this step pays for itself. Doing it by hand first also tells you whether the integration is even possible under the client's constraints, which is better to learn before the estimate than after.
Data model and one screen per real decision. The data model is derived from the steps and the rules, not from the screens. Then we build one screen per decision the operator actually makes. If a screen does not correspond to a decision, it does not get built. No dashboard for its own sake.
A prototype the owner clicks before pricing. The prototype is a standard step, offered before the meeting where price is discussed. It is not a mockup image. It is a working thing the owner can click through, with the real field names and the real sequence of steps from the interview. Owners who click a prototype give feedback that owners looking at a wireframe do not.
What the data showed
Across the projects this method has been applied to, the pattern in the evidence is consistent. The narrated day produced steps that were absent from the original requirements in every case, and the steps that were missing were almost always the ones involving a handoff between two people or two tools. The three-rule exercise surfaced at least one rule per project that had never been written down anywhere, including the marketplace rule about completed orders and outbound documents.
The hand API test changed the integration design before coding started, every time it was run. What looked like a simple "send a document when the order completes" turned out to depend on idempotency behaviour that had to be verified by sending the same payload twice and comparing responses. Without that step, the rule "a completed order never receives a new outbound document" would have been enforced only in application code, with no evidence about what the external system does on retry.
The prototype step moved feedback earlier. Comments on a working prototype arrive in the first session, and they are about the workflow, not about colours. On the deployment side, the monitoring pattern (a Telegram alert plus automatic restart on the database service) has been running for two client systems, which is where the checklist below comes from.
| Step | What we do | What it prevents | Output artefact |
|---|---|---|---|
| 1. Process as it is | One conversation, owner narrates a real day, every tool switch written down as a step | Building from the intended process instead of the real one | Numbered step list with the tool used at each step |
| 2. Non-negotiable rules | Write the rules the business cannot bend as full sentences | Vague requirements that cannot be tested | Rule sentences, each turned into a constraint and a test |
| 3. Hand API test | curl or Postman against every third-party API before coding | Discovering auth, pagination or idempotency problems after the estimate | Recorded requests and responses, including duplicate-send behaviour |
| 4. Data model and screens | Model from steps and rules, one screen per real decision | Dashboards and fields nobody uses | Schema plus a short screen list tied to decisions |
| 5. Prototype | Working prototype the owner clicks before pricing | Late feedback and rework after the quote | Clickable build with real field names |
| 6. Deploy checklist | Environment variables, backup, rollback, monitoring per project | Silent failures and no way back after a bad release | Per-project checklist, signed off before go-live |
| 7. Documentation with the code | Context file per project that the next developer reads first | Knowledge living only in one person's head | Context file in the repository, next to the code |
The fix: run the seven steps in order
The fix is not a technology choice. It is the order of operations.
Start with the narrated day. Keep the raw list. Do not clean it up before the rules step, because the messy steps are where the rules hide.
Write the rules as sentences that can be falsified. The marketplace rule is the template: a completed order never receives a new outbound document. From that sentence you get a unique constraint on the outbound document table keyed by order, a guard in the worker, and a test that sends the same completion event twice and asserts one document.
Test the APIs by hand. A curl call that proves idempotency looks like this:
curl -X POST https://api.example.com/documents \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"order_id":"TEST-1","type":"invoice"}' \
-i
# run the identical command a second time and compare status codes and bodies
If the second call returns a new document id, the rule from step 2 cannot be enforced by the external system, and your own worker has to own it. You now know this before writing the worker.
Build the data model from the steps. Then build screens that match decisions. A screen where an operator approves, rejects or escalates is a decision screen. A screen that only displays totals is usually not, and gets cut.
Ship the prototype before pricing. It does not need every branch. It needs the main path with real field names, so the owner can say "this is wrong, we never do it in that order" while changing the order is still cheap.
Deploy with the per-project checklist, every time:
- Environment variables: listed, set in the target environment, and documented in the context file.
- Backup: scheduled and verified by restoring once, not by reading the cron entry.
- Rollback: the previous version deployable with one command, tested before go-live.
- Monitoring: a Telegram alert on failure, plus automatic restart on the database service. This pattern runs for two client systems and has caught failures without anyone watching a dashboard.
Keep documentation with the code. One context file per project, at the repository root, that the next developer, or the next AI session, reads first. It states what the system does, the three rules in their sentence form, where the integration credentials live, and what the deploy checklist expects. Code and context move together in the same commit.
The full method is described at prospectia.space/en/custom-software.
How to verify the fix worked
Measure before and after on the same set of signals, and do not add new ones mid-way.
- Number of steps in the narrated day that leave the software. Before: count them during the interview. After: watch the same operator for an afternoon and count again. The direction should be down.
- Number of non-negotiable rules with a test attached. Before: zero, because the rules were not written. After: each rule maps to a named test. Run them in CI.
- Duplicate or missing documents from the integration. Before: unknown, which is the problem. After: a query on the outbound table grouped by order, expecting a maximum of one row per order for the completed-order rule.
- Time from a bad deploy to a working system. Before: however long it takes someone to notice. After: the Telegram alert fires and the database service restarts automatically, so the measure is the gap between alert and recovery.
- Time for a new developer to make a first safe change. Before: measured by asking the previous developer. After: the context file is the entry point, so the measure is whether the first change required a conversation with the original author.
If the operator still leaves the system for the same steps, the process step list was wrong, not the software. Go back to step 1 and re-run the interview.
Frequently asked questions
Why test third-party APIs by hand instead of writing an integration test first?
Because the hand test answers questions that a test written against your own assumptions cannot. You need to see the real authentication flow, the real error body, and what the external system does when you send the same request twice. A curl or Postman call gives you that in minutes. Once you know the behaviour, you write the automated test against verified reality instead of a guess.
What makes a business rule usable in software?
It has to be a sentence that can be false. "A completed order never receives a new outbound document" can be checked, so it becomes a constraint, a guard and a test. "Avoid duplicates" cannot be checked, so it becomes a comment nobody reads. Write the rules as sentences before touching the schema.
Why build a prototype before pricing instead of after signing?
Feedback on a working prototype is about the workflow, and it arrives early enough to change the estimate. Feedback after signing arrives when the workflow is already coded, and changing it costs the same as building it twice. The prototype does not need every branch, only the main path with real field names.
What belongs in the per-project deploy checklist?
Environment variables listed and set in the target environment, a backup that has been verified by restoring once, a rollback tested before go-live, and monitoring that alerts and recovers without a human watching. On the projects where this pattern runs, the alert goes to Telegram and the database service restarts automatically. The checklist is per project because the failure modes differ, but the four categories do not.
Frequently asked questions
Because the hand test answers questions that a test written against your own assumptions cannot. You need to see the real authentication flow, the real error body, and what the external system does when you send the same request twice. A curl or Postman call gives you that in minutes. Once you know the behaviour, you write the automated test against verified reality instead of a guess.
It has to be a sentence that can be false. "A completed order never receives a new outbound document" can be checked, so it becomes a constraint, a guard and a test. "Avoid duplicates" cannot be checked, so it becomes a comment nobody reads. Write the rules as sentences before touching the schema.
Feedback on a working prototype is about the workflow, and it arrives early enough to change the estimate. Feedback after signing arrives when the workflow is already coded, and changing it costs the same as building it twice. The prototype does not need every branch, only the main path with real field names.
Environment variables listed and set in the target environment, a backup that has been verified by restoring once, a rollback tested before go-live, and monitoring that alerts and recovers without a human watching. On the projects where this pattern runs, the alert goes to Telegram and the database service restarts automatically. The checklist is per project because the failure modes differ, but the four categories do not.