The Written-Scope Habit That Stopped Rework

Most rework on custom software is not “bad coding.” It is two people remembering different meetings. We stopped a large share of that by refusing to build from vibes: every paid build starts with a short written scope both sides can point at. This is the written-scope habit that cut our rework cycles - and how you can insist on it even if you are non-technical.

For the full delivery picture (discovery → UAT → support), use the complete guide to custom software for SMEs in Kenya. Here we zoom into one artefact.

What we mean by “written scope”

Not a 60-page contract novel. A living one-to-five page document (plus a simple screen list) that answers:

1. Who uses the system (roles)
2. What they can do in version 1 (capabilities)
3. Which data matters
4. What integrations are in / out
5. What “done” means for acceptance
6. Explicit out-of-scope list
7. Assumptions and open questions

If it only lives in WhatsApp voice notes, it is not scope. It is folklore.

Why verbal scope creates rework

Verbal moment	What happens weeks later
“Make it like our spreadsheet”	Debates which columns and which sheet
“Include M-Pesa”	STK vs C2B vs reconciliation unknown
“Admin can do everything”	Dangerous permissions + missing audit
“Should be ready by month-end”	Features still being invented mid-sprint
“Also add reports”	Infinite dashboard wishlist

Each mismatch becomes a “quick change” that is actually a new project. Written scope does not remove change - it prices and sequences it.

The one-page skeleton we actually use

Copy this into a shared doc. Fill it before large invoices.

1. Problem in one paragraph

What breaks today? Who feels the pain? What happens if we do nothing for six months?

2. Roles

Role	Primary jobs in v1	Not in v1
Cashier / frontline	…	…
Manager	…	…
Owner / admin	…	…
External (if any)	…	…

3. Capability list (must / should / later)

• Must: …
• Should: …
• Later (explicitly deferred): …

4. Screens or flows (not mockup perfection)

A numbered list is enough: Login → Daily sales → End-of-day report → …

5. Integrations

System	Direction	In v1?
M-Pesa / bank	…	Yes/No
SMS	…	Yes/No
Accounting export	…	Yes/No

6. Acceptance tests (10–20 bullets)

“Manager can export last week’s sales as CSV.” Pass/fail - not vibes.

7. Out of scope

Say it loudly. Examples: native iOS app, multi-branch transfers, AI chatbot, bilingual UI.

8. Assumptions

“Staff have Android phones with Chrome.” “One branch only.” Wrong assumptions are cheaper when written early.

When you are ready to run this process with a partner, get started with discovery - the scope document is the output, not a surprise PDF after code ships.

Habits that make the document work

1. Date and version every change.
Scope v1.2 - 2025-03-10 - added stock adjust for manager. People argue with ghosts less when history is visible.

2. One owner on the client side.
Committees invent features. Name a decider who can say “later.”

3. Freeze v1 before build burns hard.
Discovery can explore. Mid-build “while we’re at it” belongs in a change log with cost/time impact - or it waits.

4. Demo against the acceptance list.
Weekly demos are theatre unless someone ticks the same bullets you signed.

5. Link tickets to scope IDs.
SCOPE-12 in the task title. Orphans without a scope ID get challenged.

Checklist before you approve a kickoff invoice

• Roles listed with permissions intention
• Must / should / later is filled (later is not empty - emptiness means unbounded)
• Out-of-scope has at least five real items
• Integrations named with “in/out”
• Acceptance tests a non-technical owner can run
• Hosting / who owns accounts noted
• Support window after launch noted [VERIFY with your vendor]
• Both parties named as reviewers on the document

If the builder resists writing this, that is a signal - treat it like other red flags when choosing a custom software developer, and keep the pillar guide close.

Handling “can’t we just start coding?”

Starting without scope feels faster for one week. It costs rework for three. A useful compromise:

1. Paid discovery sprint → written scope + clickable prototype or wireflows
2. Fixed (or capped) build on that scope
3. Change requests as separate mini-scopes

Founders sometimes fear documentation slows innovation. In SME operations software, innovation without agreement is just unpaid product management shifted onto the engineering team.

What this habit is not

• Not a substitute for conversation - workshops still matter
• Not a weapon to refuse every change - it is a filter and a price list
• Not only the developer’s job - the business owns process truth

Measuring whether it worked

Track for the next project:

Metric	Before written scope (typical pain)	Target
Change requests mid-v1	Constant, unpriced	Logged + estimated
“That’s not what we meant” moments in UAT	Frequent	Rare; traced to assumption gaps
Rework days after “done”	High	Falling
Time to agree “done”	Foggy	Acceptance list complete

You do not need scientific [VERIFY] percentages. You need the Friday feeling that demos match the document.

Bottom line

Written scope is a respect practice: for the team’s time, for the founder’s money, and for staff who will live in the software. Keep it short, keep it versioned, keep out-of-scope visible, and attach acceptance tests. That single habit stopped more rework for us than any new framework.

When you want the surrounding process - discovery through maintenance - return to the SME custom software guide. Bring the scope skeleton to questions before hiring a web developer conversations so vendors cannot dodge specificity. Scope is the hinge; the rest of delivery swings on it.