The brief, as it usually arrives
“We're a recruitment agency. Everything is in spreadsheets and the recruiters lose track of
candidates. We need a proper system.”
The five questions we ask before quoting anything
- Where does a candidate actually get lost? Between first call and client submission,
or after submission while waiting on the client? These are two different tools. (Assume: the
second — it is the usual answer, and it is the one that costs the agency money.)
- Who else must see this? Recruiters only, or do client-side hiring managers log in?
A client-facing portal roughly doubles the surface: permissions, invitations, an audit trail.
- What is the single number the owner checks on Monday morning? That number defines
the dashboard. Everything else is a nice-to-have.
- Where do CVs live today, and must they stay there? Google Drive is an integration.
Uploading into our own storage is not. The answer changes a week of work.
- How many open roles at once, and how many candidates per role? 40 roles × 30
candidates is a list view. 400 × 300 is a search problem, and a different quote.
What we would build — the scope that fits 4 weeks
One workflow: candidate moves from sourced to placed, and the
agency always knows who is waiting on whom.
| Data model | Why it is shaped this way |
Role — client, title, fee basis, status | The billable unit. Everything hangs off it. |
Candidate — person, contact, CV link | Exists independently of any role, so one person can be put forward twice. |
Submission — role × candidate, stage, owner, next action, due date | The join table is the product. "Lost candidates" is always a missing next-action-plus-owner. |
StageEvent — append-only history | Lets us answer "how long do we sit in client review" without any extra reporting work later. |
Eight screens: role list · role detail with its pipeline · candidate list · candidate
detail · submission drawer (stage, owner, next action) · my-week view (everything due, by owner)
· owner dashboard (time-in-stage, placements this month, CSV export) · admin (users, clients,
stage names).
Two integrations: Google sign-in, so nobody manages another password. Google Drive, so
CVs stay where recruiters already put them — we store a link and a permission check, not a copy.
What we would deliberately cut, and say so on day one
- WhatsApp integration. Everyone asks. The Business API needs a Meta business
verification and message templates approved by Meta — a dependency we do not control,
inside a four-week fixed date. We ship a copy-to-WhatsApp button instead: same
minute saved, none of the risk.
- CV parsing / AI ranking. Accuracy here is unbounded work and the acceptance test
would be a matter of taste. Out of scope by name, in writing.
- Email sync. Reading recruiters' inboxes is a second project with its own privacy
conversation.
- Bulk import of three years of old spreadsheets. Excluded. We import open roles only;
history stays in Sheets, read-only.
Named risks, and who carries them
| Risk | Our answer |
| Drive permissions differ per recruiter, so a CV link 404s for a colleague | Ours. We check access at render time and show an explicit "ask the owner for access" state rather than a broken link. |
| Stage names get argued about in week 3 and the workflow changes | Shared. Stages are admin-configurable data, not code — so the argument costs an afternoon, not a change order. |
| Recruiters keep using the spreadsheet in parallel | Yours, and it is the real risk. Mitigation is the Monday dashboard: once the owner reads placements from the tool, the spreadsheet stops being the source of truth within a week. |
The acceptance test we would sign
On the production URL, by the end-of-week-4 date: a recruiter signs in with Google, creates a
role, attaches two candidates, advances one through every stage to placed, and the
owner dashboard shows that placement plus a correct average time-in-stage, exported to CSV. Any
item in the signed scope that does not do this is a defect and is fixed free inside the 14-day window.
Effort estimate [illustrative]: ~170 hours of equivalent senior
engineering. That is a Launchpad, at the 8-screen and 2-integration ceiling — not below it.
If questions 2 or 5 above come back the other way (a client portal, or 400 live roles), this is a
Buildout and we say so before quoting, not in week 3.