A proposal is a gate, not a report. One to two pages. It is read out loud in front of the class, in a few minutes, against six questions — plus one obligation you owe the client. If a section here takes you more than a short paragraph, you are writing the wrong document.
See one finished. The worked example is a real repository with an accepted proposal in it, the same content published as a page, and the rest of a finished Phase 1 around it.
How to use this page. Create docs/proposal.md
in your team repository with the eight section headings from Part 1, and
fill them in. Your proposal is those eight sections and nothing else. Parts 2
and 3 on this page are teaching, not template — do not copy them in.
How it is submitted. Two ways, and both are required.
-
As
docs/proposal.mdin the team repository. This is the document that is judged, read against the six questions below — write it in sentences, because “what happens today, step by step, and how often” is exactly what a list of bullet points destroys, and a solution in search of a problem is the most common reason a proposal comes back. -
As the same content, published as a page from the team's own
repository —
docs/index.html. The proposal is presented from that live address when proposals are reviewed. How that file gets a public address is in the publishing guide. This one is checked as done or not done — reachable at a public address, or not — as part of the verified environment. It is not judged on how it looks.
The mechanics are not taught in class. See the publishing guide for the steps.
If it is returned. A rejected proposal comes back within three calendar days. The first resubmission carries no penalty — a rejection is the course working as designed. A second resubmission caps that component at half its marks. Nothing passes the end of week 3 unaccepted; at that point a project is assigned to you.
The bar — all six must hold
Six things are asked of every project. They are listed here once, in full, because together they are what acceptance means: a proposal is accepted when all six hold, and returned when any one of them does not.
- Real — a named client outside this room, with a problem they actually have.
- Business value — someone is measurably better off: money saved, time saved, a better decision.
- A plausible next life — it could be sold to a business, or adopted by a public organisation.
- Finishable — what you described is done by the final week of the semester.
- Reachable — that client will meet you, and answer late in the semester.
- Enough data — information that must still be there tomorrow, meaning a real database.
All six must hold. The instructor answers each one while listening to your team present. So the proposal has to make all six visible without their being hunted for — if one of them is true but nowhere in the document, it is not visible, and the answer to that one is no.
Why a proposal is returned
Five proposals, and the reason each one comes back. These are the words the rejection is given in.
| Proposal | Why it is returned |
|---|---|
| A to-do list app | No client, and nobody is better off |
| “An app for a restaurant” | A solution, not a problem |
| A platform for every clinic in Kuwait | Cannot be finished by the final week of the semester |
| A copy of an existing product | The problem is already solved |
| A client who will not meet you | Nothing to verify, nobody to accept it |
Two things are not returns: a proposal that is really two projects gets cut in the room, with the second half named as out of scope, and a proposal too small for your team gets widened in the room. Under-scoping is the cheaper mistake. Part 3 works three of the five rows above out on one client.
Part 1 — What a proposal must contain
Eight sections. Each one answers a question you will be asked in the room. The right-hand column is the question, in the words it is asked in.
| # | Section | Length | The question it answers |
|---|---|---|---|
| 1 | The client, and how you reach them | 3–4 lines | Real — a named client outside this room, with a problem they actually have · Reachable — will they meet you, and answer late in the semester |
| 2 | What happens today, and what goes wrong | 1 short paragraph or 4–6 steps | Real — a problem they actually have, described as a problem and not as a solution |
| 3 | Who is better off, and how you would know | 3–4 lines | Business value — someone measurably better off: money saved, time saved, a better decision |
| 4 | What the system does, in outline | 4–6 bullets | Finishable — is what you described done by the final week of the semester |
| 5 | What it records | 4–6 lines | Enough data — information that must still be there tomorrow, i.e. a real database |
| 6 | In scope by the final week — and what is not | Two short lists | Finishable — and it is what protects you when the client asks late for something nobody agreed to |
| 7 | The next life | 2 lines | A plausible next life — could it be sold to a business, or adopted by a public organisation |
| 8 | What you told the client this is | 3 lines | Not one of the six — the disclosure you owe the client, said in the first meeting, and checked alongside the proposal |
Two things this document is not judged on, so do not put them in: the technology (the stack is given by the course and is not your decision) and the presentation. Sections 2 and 3 in particular should be readable by someone who has never heard of a database.
1. The client, and how you reach them
The organisation's actual name, the contact by role, how your team reached them, and the fact that they have agreed to meet and will answer late in the semester.
A category is not a name. “A restaurant”, “some clinic”, “a charity in Kuwait” all fail here. Neither is a name you found online and have not spoken to. If you have not had the first meeting yet, you are not ready to submit.
Fill in: Organisation · contact by role · how you reached them · what they agreed to.
2. What happens today, and what goes wrong
The problem in the client's own terms. What happens today, step by step. What goes wrong. How often. Name no technology here at all — not the one you plan to build and not the one they use now.
The test: could this sentence be wrong? “We will build an app for them” cannot be wrong, so it cannot be checked, so it is not a problem statement. “Orders are taken on paper and about four a week are lost” can be wrong — which is exactly why it is worth something.
Fill in: what happens today · what goes wrong · how often.
3. Who is better off, and how you would know
Name the person or the organisation who ends up better off, say in what — money, time, or a decision they can now make — and say the number you would look at to know whether it worked. An estimate from the client is fine. An honest rough figure beats a confident invented one.
Fill in: who · better off in what · the number you would check.
4. What the system does, in outline
Four to six bullets, in the words of the people who will use it, by role. Not screens, not features, not architecture — what a person can do, and what the system will not let them do.
Fill in: 4–6 bullets, each starting with a role.
5. What it records
The information that must still be there tomorrow, and next month. List the things the system remembers and, in one line, why the client's question cannot be answered without remembering them.
If everything your system does dies when the page closes — a calculator, a converter, a form that emails itself — you do not have enough data, and that is a rejection.
Fill in: the things recorded · the one question that requires remembering them.
6. In scope by the final week — and what is not
Two lists. What will exist by the final week of the semester, and what will not.
The second list is the one teams skip and the one that protects them. Write it now, while nobody wants anything yet. One client, one workflow, done, beats three started.
Fill in: In scope · Not in scope (this semester).
7. The next life
Two lines. Who else, beyond this client, would pay for this or adopt it — another business of the same kind, or a public organisation.
This is plausibility, not a business plan. Nobody is asking you to price it.
Fill in: who else would use it, and why.
8. What you told the client this is
This is an obligation to the client rather than one of the six, and it is checked alongside the proposal. Confirm, in three lines, that you said this in the first meeting:
- a coursework prototype, built by students;
- publicly visible at a public address;
- unsupported after the final week of the semester.
A client who agreed to a prototype is a good client. A client who thought they were getting a supported product is a complaint.
Fill in: confirm you said it, and to whom.
Part 2 — A worked example that would be accepted
Read this for its shape and its honesty, not for its ambition. It is deliberately ordinary. Ordinary and well-defined is accepted ahead of impressive and vague.
This specific project may not be proposed by any team. It is worked here as an example, so it is off the table. So are the examples used in class.
1. The client, and how you reach them
Al-Nahda Charitable Society, Jahra branch — a registered charity that distributes monthly food baskets. Our contact is the branch distribution coordinator. A member of our team volunteers at the branch and introduced us. We met the coordinator once at the branch; the coordinator has agreed to a short meeting every two weeks and to answer by phone through the end of the semester, and has asked to see the system before the final month.
2. What happens today, and what goes wrong
Roughly 300 families are registered for a monthly basket. The register is a paper folder at the branch, plus a spreadsheet one volunteer keeps on a personal laptop; the two do not always agree.
- A family fills in a paper form at the branch and it goes into the folder.
- Before each distribution, a volunteer types a printed list from the folder.
- On distribution day, volunteers tick names off the printed list at the hall.
- A separate volunteer takes a second copy of the list on the home-delivery round.
What goes wrong: because the hall list and the delivery list are separate pieces of paper, some families collect twice in the same month — the coordinator estimates 8 to 12 baskets a month. In the other direction, two or three eligible families a month are missed entirely, because their paper form was never copied onto the printed list. And when a donor asks who received baskets over a given period, it takes the coordinator about two days to reconstruct the answer from the folder.
3. Who is better off, and how you would know
The branch. At roughly KD 12 a basket, the duplicates cost about KD 100–150 a month in baskets that were not needed, and the missed families are the ones the branch exists to serve. The coordinator gets back about two days per donor report.
We would know from two numbers the system itself can produce: duplicate collections recorded per distribution (should fall to zero) and time to produce a monthly report (minutes, not days).
4. What the system does, in outline
- A volunteer registers a family once — household size, area, contact, and the date its eligibility was last reviewed.
- A volunteer looks a family up on distribution day and records the basket as collected.
- The system refuses a second collection by the same family in the same month, and shows who recorded the first one and where.
- The coordinator sees one screen for the day: who has collected and who has not.
- The coordinator produces a monthly report — baskets given, by area, and families who have not collected for three months.
- A volunteer sees only the distribution list; the register and the reports are the coordinator's.
5. What it records
Families, with household size, area, contact and eligibility review date. Volunteers. Distributions — a month and a location. Collections — which family, at which distribution, recorded by which volunteer, and when.
The whole point of the system is the question “has this family already collected this month?”, and that is a question about the past. It cannot be answered unless last week's collections are still there this week.
6. In scope by the final week — and what is not
In scope: one branch. One basket type. The family register. The duplicate check. The distribution-day screen. The monthly report. Two roles — volunteer and coordinator.
Not in scope this semester: other branches; cash assistance and any other form of aid; planning the home-delivery route; messaging families; any access for families themselves; and loading the historic paper folder — we enter the current register only.
7. The next life
The other branches of the same society run the identical monthly distribution, and so do other registered charities in Kuwait. The duplicate check is the part that would be adopted first, and a public body that oversees registered charities would plausibly want the same record.
8. What you told the client this is
At the first meeting we told the coordinator that this is a coursework prototype built by students, that it will be publicly visible at a public address, and that it is unsupported after the final week of the semester. The coordinator understood this and asked that no family contact numbers be used in anything demonstrated publicly.
Part 3 — The same client, done badly
Same charity, three proposals that get returned. Each is annotated with the reason in the words from the rejection table, and what specifically triggered it.
Most returns are the second kind, and the second kind is a rewrite, not a new project — the team usually has a real problem underneath and has described it backwards.
Bad version A — “A solution, not a problem”
Section 2 as written: “We will build a donation management app for Al-Nahda Charitable Society. It will have a dashboard, a database of families, and a mobile-friendly interface so volunteers can manage everything in one place.”
Why it is returned: A solution, not a problem. Nothing in that paragraph can be wrong, so nothing in it can be checked. It never says what happens today, what goes wrong, or how often. “Manage everything in one place” is not a problem anyone has — it is a description of software. Note also that it names technology in the one section that must not.
What must change: the same project, rewritten. Go back to the four questions — what happens today, step by step; what goes wrong; how often; who else touches this — and write the answers down. The duplicate baskets were always the problem; this version just never mentioned them.
Bad version B — “A client who will not meet you”
Section 1 as written: “Our client is a charitable society in Jahra. We found their number on their Instagram page and sent a message. We will confirm the details with them once the proposal is approved.”
Why it is returned: A client who will not meet you — nothing to verify, and nobody to accept it. Nobody has met anyone. An unanswered message is not a client, and “a charitable society in Jahra” is a category, not a name. There is no one who can tell you the register is wrong, and no one who can accept the finished system.
Had the section named the branch and the coordinator but admitted they had declined to meet, it is still returned — for the same reason. A named client who will not meet you fails just as a nameless one does.
What must change: produce a client who has actually agreed to meet, or change the client. Start with someone your team already knows who runs something. Proximity beats ambition.
Bad version C — “Cannot be finished by the final week of the semester”
Section 6 as written: “In scope: a platform for all registered charities in Kuwait. Any charity can sign up and manage its own families, volunteers, drivers and donors. Families log in to request aid and track their application. Delivery drivers get routes on a mobile app. An SMS goes out when a basket is ready, and a national dashboard shows total aid distributed across all participating charities.”
Why it is returned: Cannot be finished by the final week of the semester. This is three semesters of work and at least four kinds of user. The national dashboard also needs data from organisations nobody on the team has spoken to.
What must change: cut to one client and one workflow, and name what is out of scope. One branch, one basket, the duplicate check and the monthly report — the accepted version above is what is left after that cut. It is the same idea, honestly sized.
The two that are not rejections
Worth knowing, so you do not over-correct:
- Really two projects. Not a rejection. It gets cut in the room and the second half is named as out of scope.
- Too small for your team for a semester. Not a rejection either. Scope gets widened in the room — a second role, a report, or the admin side.
Neither costs you three days. Under-scoping is a cheaper mistake than over-scoping.